Ims Java Users Guide
This document was uploaded by user and they confirmed that they have the permission to share it. If you are author or own the copyright of this book, please report to us by using this DMCA report form. Report DMCA
Overview
Download & View Ims Java Users Guide as PDF for free.
More details
- Words: 48,031
- Pages: 143
IMS Version 7
IMS Java User’s Guide
SC27-0832-02
IMS Version 7
IMS Java User’s Guide
SC27-0832-02
Note Before using this information and the product it supports, be sure to read the general information under “Notices”.
Third Edition (August 2002) (Softcopy Only) This edition replaces and makes obsolete the previous edition, SC27-0832-01. This edition is available in softcopy format only. The technical changes for this version are summarized under “Summary of Changes” on page xvii. The technical changes for this edition are indicated by a vertical bar to the left of a change. © Copyright International Business Machines Corporation 2000, 2002. All rights reserved. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents Figures
. . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
| |
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . xv Prerequisite Knowledge . . . . . . . . . . . . . . . . . . . . . . xv Change Indicators . . . . . . . . . . . . . . . . . . . . . . . . xv
| |
Summary of Changes . . . . . . . . . . . . . . . . . . . . . xvii Changes to The Current Edition of This Book for IMS Version 7 . . . . . . xvii Library Changes for IMS Version 7 . . . . . . . . . . . . . . . . . xvii
| | | | | |
Chapter 1. Overview of IMS Java . . . . Design Process . . . . . . . . . . . IMS Environment Overview . . . . . . . WebSphere for z/OS Environment Overview CICS Environment Overview . . . . . . DB2 Environment Overview. . . . . . .
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Chapter 2. Setting Up Your Environment for IMS Java. . . . . . . . . . 3 System Requirements for All Environments . . . . . . . . . . . . . . . 3 General Restrictions . . . . . . . . . . . . . . . . . . . . . . . 3 IMS Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 IMS System Requirements . . . . . . . . . . . . . . . . . . . . 4 IMS Restrictions . . . . . . . . . . . . . . . . . . . . . . . . 4 IMS Configuration . . . . . . . . . . . . . . . . . . . . . . . 4 Configuring a JMP Region . . . . . . . . . . . . . . . . . . . 4 Configuring a JBP Region . . . . . . . . . . . . . . . . . . . 5 IMS Installation Verification . . . . . . . . . . . . . . . . . . . . 6 WebSphere for z/OS Setup . . . . . . . . . . . . . . . . . . . . . 8 WebSphere for z/OS System Requirements. . . . . . . . . . . . . . 8 WebSphere for z/OS Restrictions . . . . . . . . . . . . . . . . . 8 WebSphere for z/OS Configuration . . . . . . . . . . . . . . . . . 9 Configuring the WebSphere for z/OS J2EE Server for IMS Access . . . . 9 Configuring the WebSphere for z/OS J2EE Server to Locate the IMS JDBC Resource Adapter . . . . . . . . . . . . . . . . . . . . . 9 Deploying an Instance of the IMS JDBC Resource Adapter . . . . . . 10 Deploying an EJB onto a WebSphere for z/OS J2EE Server . . . . . . 11 WebSphere for z/OS Installation Verification . . . . . . . . . . . . . 12 CICS Setup . . . . . . . . . . . . . . . . . . . . . . . . . . 13 CICS System Requirements . . . . . . . . . . . . . . . . . . . 13 CICS Restrictions . . . . . . . . . . . . . . . . . . . . . . . 13 CICS Configuration . . . . . . . . . . . . . . . . . . . . . . 13 Installation Verification . . . . . . . . . . . . . . . . . . . . . 14 DB2 Setup . . . . . . . . . . . . . . . . . . . . . . . . . . 15 DB2 System Requirements . . . . . . . . . . . . . . . . . . . 15 DB2 Restrictions . . . . . . . . . . . . . . . . . . . . . . . 15 DB2 Configuration. . . . . . . . . . . . . . . . . . . . . . . 15 ENVAR Settings for the JAVAENV Data Set . . . . . . . . . . . . 16 DB2 Installation Verification . . . . . . . . . . . . . . . . . . . 17 © Copyright IBM Corp. 2000, 2002
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
1 1 1 2 2 2
iii
| | |
DLIModel Utility Setup . . . . . . . . . . . . . . . . . . . . . . 19 Preparing the DLIMODEL MVS Procedure . . . . . . . . . . . . . . 19 Preparing to Run From the MVS USS Prompt . . . . . . . . . . . . 21
| | | | | | | | | | | | | | | | | | | | | | | | | |
Chapter 3. Accessing an IMS Database . . . . Introduction to the Example Environment . . . . JDBC Access Method . . . . . . . . . . . Describing Your IMS Databases to IMS Java . . Using JDBC to Access an IMS Database . . . Classes and Field Names . . . . . . . . PCB-Qualifying SQL Queries. . . . . . . Writing an Application that Uses JDBC . . . Supported Data Types in IMS Java . . . . . General Mappings from COBOL Copybook Types Types . . . . . . . . . . . . . . . Supported SQL Grammar . . . . . . . . . . SELECT . . . . . . . . . . . . . . . Segment-Qualifying Fields. . . . . . . . FROM . . . . . . . . . . . . . . . . WHERE . . . . . . . . . . . . . . . INSERT . . . . . . . . . . . . . . . DELETE . . . . . . . . . . . . . . . UPDATE . . . . . . . . . . . . . . . JDBC Prepared Statements for SQL . . . . . Recommendations for JDBC . . . . . . . . IMS Java Hierarchic Database Interface . . . . Application Programming Using DLIConnection . Creating a DLIConnection Object . . . . . . Building SSAs . . . . . . . . . . . . . Accessing DL/I Data using SSAs . . . . .
|
Chapter 4. Writing a Java Application Program . . . . . . . IMS Applications . . . . . . . . . . . . . . . . . . . Overview of IMS Application Processing . . . . . . . . . Running Java Applications. . . . . . . . . . . . . . Message Queuing. . . . . . . . . . . . . . . . . Reading and Writing Messages to the Message Queue in Java Building an IMS Java Application by Example . . . . . . . Using IMS Java to Build a Message Processing Application . Programming Models for IMS Java Applications . . . . . . . JMP Programming Models . . . . . . . . . . . . . JBP Programming Models . . . . . . . . . . . . . . Additional Programming Considerations . . . . . . . . . . Conversational Transactions . . . . . . . . . . . . . Handling Multi-Segment Messages . . . . . . . . . . Coding and Accessing Messages with Repeating Structures . Flexible Reading of Multiple Input Messages . . . . . . . CICS Applications . . . . . . . . . . . . . . . . . . . DB2 Stored Procedures . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
45 45 45 46 46 46 46 46 49 50 51 52 52 54 55 56 59 59
Chapter 5. DLIModel Utility . . . . . . . . . . DLIModel Utility Overview . . . . . . . . . . . Requirements and Restrictions of the DLIModel Utility Requirements . . . . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . Output Types of the DLIModel Utility . . . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
61 61 63 63 63 64
| | |
|
| | | | | |
iv
IMS Java User’s Guide
. . . . . . . . . to . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . IMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . and Java Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
23 23 24 24 27 27 28 29 32 33 34 35 35 37 37 38 39 39 40 40 41 42 42 42 43
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
|
|
| | | | | |
IMS Java Metadata Classes . . . . . . . . . . DLIModel Java Report . . . . . . . . . . . . PSB Description . . . . . . . . . . . . . PCB Description . . . . . . . . . . . . . Segment Description . . . . . . . . . . . . Field Description . . . . . . . . . . . . . XMI Description of the Databases . . . . . . . . DLIModel Trace . . . . . . . . . . . . . . Control Statements for the DLIModel Utility . . . . . Control Data Set Rules . . . . . . . . . . . . Control Statement Rules . . . . . . . . . . . Control Statement Syntax . . . . . . . . . . . OPTIONS Statement. . . . . . . . . . . . PSB Statement . . . . . . . . . . . . . . PCB Statement . . . . . . . . . . . . . . SEGM Statement . . . . . . . . . . . . . FIELD Statement . . . . . . . . . . . . . XDFLD Statement. . . . . . . . . . . . . INCLUDE Statement . . . . . . . . . . . . Comment Statement . . . . . . . . . . . . Running the DLIModel Utility . . . . . . . . . . . Running the DLIModel Utility as an MVS Job . . . . PROC Statement Parameters . . . . . . . . Step 1 EXEC Statement Parameters . . . . . . Step 1 DD Statements . . . . . . . . . . . Step 2 EXEC Statement Parameters . . . . . . Step 2 DD Statements . . . . . . . . . . . Running the DLIModel Utility From MVS Unix Systems Examples of Using the DLIModel Utility . . . . . . . Example 1. Simple Example . . . . . . . . . . Example 2. Example With a Logical Relationship . . Example 3. Example With a Secondary Index . . . Example 4. Example with Multiple Control Statements
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Services . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
64 64 64 64 64 64 65 66 66 66 68 68 68 70 70 70 71 73 73 74 74 74 75 75 75 76 76 77 77 77 79 83 85
Chapter 6. Problem Determination . . . . . . . . Exceptions . . . . . . . . . . . . . . . . . How Exceptions Map to DL/I Status Codes . . . . SQLExceptions . . . . . . . . . . . . . . . Sync Point Failure. . . . . . . . . . . . . . . GU Message Failure . . . . . . . . . . . . . . Abends. . . . . . . . . . . . . . . . . . . ABENDU0118 - Commit Failure . . . . . . . . . ABENDU0475 - Batch Run Failure . . . . . . . Processing Dumps . . . . . . . . . . . . . DLIModel Messages . . . . . . . . . . . . . . IMSTrace . . . . . . . . . . . . . . . . . . Initiating IMSTracing . . . . . . . . . . . . . Setting up Tracing for the IMS Java Library Routines . Adding Trace Statements to Your Application . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
91 91 91 92 93 93 93 93 94 94 94 96 96 96 97
Appendix A. Manually Creating IMS Java Metadata Mapping an IMS Database in Java Classes . . . . IMS Database Definition (DBD) . . . . . . . . Adding Default Values for Fields of a Segment . . Mapping the PSB to DLIDatabaseView . . . . DLIDatabaseView Example . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
Classes . . . . . . . . . . . . . . . . . . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. 99 . 99 . 99 . 99 . . . . . . 100 . . . . . . 101 Contents
v
DLISegment Example . . . . . . . . . . . . . . . . . . . . . 103
|
Appendix B. High Performance Java . . . . . . . . . . . . . . . 105 Compile and Runtime Options . . . . . . . . . . . . . . . . . . . 105 Installation Verification Process . . . . . . . . . . . . . . . . . . 107 Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . 111 IMS Version 7 Library . . . . . . . . . . . . . . . . . . . . . . 111 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
vi
IMS Java User’s Guide
Figures | | | | | | | | | | | | | | | | | | |
|
|
| | | | | | | | | | | | | | | | | | | | | | | |
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. 39. 40. 41. 42. 43. 44. 45. 46. 47. 48. 49. 50. 51. 52. 53.
Example of a Blank IMS Installation Verification Procedure Screen . . . . . . . . . . Example IMS Installation Procedure Screen with Transaction Input Information . . . . . Example IMS Installation Verification Procedure Screen with Transaction Output Information Example Database Hierarchy . . . . . . . . . . . . . . . . . . . . . . . Example PSB Definition . . . . . . . . . . . . . . . . . . . . . . . . . DBD Sample Definition . . . . . . . . . . . . . . . . . . . . . . . . . The IMS Java Summary Report . . . . . . . . . . . . . . . . . . . . . . IMS DB Segments and Fields with Their Corresponding DB2 Tables and Columns . . . PCB-Qualifying SQL Query Example . . . . . . . . . . . . . . . . . . . . JDBC Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . Establish a Database Connection . . . . . . . . . . . . . . . . . . . . . . Example of SELECT Query Results . . . . . . . . . . . . . . . . . . . . . Sample Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample INSERT Statement . . . . . . . . . . . . . . . . . . . . . . . . Sample DELETE Statement . . . . . . . . . . . . . . . . . . . . . . . . Sample UPDATE Statement. . . . . . . . . . . . . . . . . . . . . . . . Creating a DLIConnection Object . . . . . . . . . . . . . . . . . . . . . . Creating an SSAList . . . . . . . . . . . . . . . . . . . . . . . . . . Subclass IMSFieldMessage: Input Message Sample Code . . . . . . . . . . . . Subclass IMSFieldMessage: Output Message Sample Code . . . . . . . . . . . . Subclass IMSApplication Sample Code . . . . . . . . . . . . . . . . . . . Defining a SPA Message . . . . . . . . . . . . . . . . . . . . . . . . . Reading the SPA Message . . . . . . . . . . . . . . . . . . . . . . . . Writing the SPA Message. . . . . . . . . . . . . . . . . . . . . . . . . Example Output Message . . . . . . . . . . . . . . . . . . . . . . . . Defining the Primary Input Message . . . . . . . . . . . . . . . . . . . . . Creating the Input Messages . . . . . . . . . . . . . . . . . . . . . . . Message Reading Logic . . . . . . . . . . . . . . . . . . . . . . . . . The DLIModel Utility Inputs and Outputs . . . . . . . . . . . . . . . . . . . Sample DLIModel Utility PROC . . . . . . . . . . . . . . . . . . . . . . Physical DBD for Simple Example . . . . . . . . . . . . . . . . . . . . . PSB for Simple Example . . . . . . . . . . . . . . . . . . . . . . . . . Minimal MVS JCL stream. . . . . . . . . . . . . . . . . . . . . . . . . Control Data Set for Simple Example . . . . . . . . . . . . . . . . . . . . DLIModel Java Report for Simple Example . . . . . . . . . . . . . . . . . . EMPDB2 Physical DBD for Logical Relationship Example . . . . . . . . . . . . . DEALDB2 Physical DBD for Logical Relationship Example . . . . . . . . . . . . Logical DBD for Logical Relationship Example . . . . . . . . . . . . . . . . . PSB with Field-Level Sensitivity for Logical Relationship Example . . . . . . . . . . Control Data Set for Logical Relationship Example . . . . . . . . . . . . . . . DLIModel Java Report for Logical Relationship Example . . . . . . . . . . . . . DBD for Secondary Index Example . . . . . . . . . . . . . . . . . . . . . Logical DBD for Secondary Index Example . . . . . . . . . . . . . . . . . . PSB for Secondary Index Example . . . . . . . . . . . . . . . . . . . . . MVS USS Command for Secondary Index Example . . . . . . . . . . . . . . . Control Data Set for Secondary Index Example . . . . . . . . . . . . . . . . DLIModel Java Report for Secondary Index Example . . . . . . . . . . . . . . Physical DBD for Multiple Control Statements Example. . . . . . . . . . . . . . PSB for Multiple Control Statements Example . . . . . . . . . . . . . . . . . MVS USS Command for Control Statements Example . . . . . . . . . . . . . . Top-Level Control Data Set for Multiple Control Statements Example. . . . . . . . . Second-Level Control Data Set for Multiple Control Statements Example . . . . . . .
© Copyright IBM Corp. 2000, 2002
. . . 7 . . . 7 . . . 8 . . . 24 . . . 25 . . . 25 . . . 26 . . . 28 . . . 29 . . . 30 . . . 31 . . . 36 . . . 37 . . . 37 . . . 38 . . . 39 . . . 39 . . . 42 . . . 43 . . . 47 . . . 48 . . . 49 . . . 53 . . . 53 . . . 54 . . . 56 . . . 57 . . . 58 . . . 59 . . . 62 . . . 75 . . . 78 . . . 78 . . . 78 . . . 78 . . . 79 . . . 80 . . . 80 . . . 81 . . . 81 . . . 82 . . . 82 . . . 83 . . . 84 . . . 84 . . . 84 . . . 84 . . . 85 . . . 86 . . . 86 . . . 86 . . . 87 . . . 88
vii
| 54. DLIModel Java Report for Multiple Control Statements Example . . . . . . | 55. Database access methods of DLIConnection . . . . . . . . . . . . . 56. IMSException Sample . . . . . . . . . . . . . . . . . . . . . . | 57. Setting a Trace within a Static Method . . . . . . . . . . . . . . . . 58. Setting Up IMSTrace . . . . . . . . . . . . . . . . . . . . . . | 59. Example Database and Segments . . . . . . . . . . . . . . . . . | 60. DBD Sample Definition . . . . . . . . . . . . . . . . . . . . . | 61. DLIDatabaseView Example Code . . . . . . . . . . . . . . . . . | 62. Example DLISegment Code . . . . . . . . . . . . . . . . . . . 63. -exclude statement example . . . . . . . . . . . . . . . . . . . 64. Binding the class files . . . . . . . . . . . . . . . . . . . . . 65. Example of a Blank IMS Installation Verification Procedure Screen . . . . . 66. Example IMS Installation Procedure Screen with Transaction Input Information 67. Example IMS Installation Verification Procedure Screen with Transaction Output
viii
IMS Java User’s Guide
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Information
. . . . . .
. . . . . . . . . . . . .
. 89 . 92 . 92 . 97 . 97 . 99 . 100 . 102 . 103 . 106 . 106 . 108 . 108 109
Tables 1. 2. 3. 4. 5. 6. | 7. | | | | |
Supported Data Types . . . . . . . . . . . . . . . . . ResultSet.getxxx Methods to Retrieve JDBC Types . . . . . . Mapping from COBOL to IMS and Java . . . . . . . . . . DLITypeInfo Constants and Java Types based on PICTURE clause CopyBook Formats Mapped to IMS Java Types . . . . . . . Status Code, Reason, and Return Code . . . . . . . . . . Status Code, Reason, and Return Code . . . . . . . . . .
© Copyright IBM Corp. 2000, 2002
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
32 33 34 34 34 93 93
ix
x
IMS Java User’s Guide
Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user’s responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs © Copyright IBM Corp. 2000, 2002
xi
and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation J46A/G4 555 Bailey Avenue San Jose, CA 95141-1099 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurement may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. All statements regarding IBM’s future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only. This information is for planning purposes only. The information herein is subject to change before the products described become available. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrates programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBM’s application programming interfaces.
xii
IMS Java User’s Guide
Each copy or any portion of these sample programs or any derivative work, must include a copyright notice as follows: © (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rights reserved. If you are viewing this information softcopy, the photographs and color illustrations may not appear.
Trademarks The following terms are trademarks of the IBM Corporation in the United States or other countries or both: BookManager DB2 CICS IBM IMS
MVS OS/390 WebSphere z/OS
Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc., in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Other company, product, and service names may be trademarks or service marks of others.
Notices
xiii
xiv
IMS Java User’s Guide
Preface | | |
This book explains how to configure your system for IMS Java application support, how to build IMS Java metadata classes using the DLIModel utility, and how to write Java application programs that access IMS databases. This softcopy book is available only in PDF and BookManager formats. This book is available on the IMS Version 7 Licensed Product Kit (LK3T-3526). You can also get the most current versions of the PDF and BookManager formats by going to the IMS Web site at www.ibm.com/ims and linking to the Library page.
|
Prerequisite Knowledge
| | | |
To configure your system for IMS Java, you must understand system administration for your system (IMS, WebSphere Application Server, CICS, or DB2). For IMS system administration, you should know the concepts in IMS Version 7 Administration Guide: System.
| | |
To create IMS Java metadata classes, which is a required step in writing IMS Java applications, you must understand IMS databases. IMS database concepts are described in IMS Version 7 Administration Guide: Database Manager.
| | |
To write IMS Java applications, you must thoroughly understand the Java language and JDBC. This book assumes that you know Java and JDBC. It does not explain any Java or JDBC concepts.
| | |
Change Indicators Technical changes are indicated in this publication by a vertical bar ( | ) to the left of the changed text.
© Copyright IBM Corp. 2000, 2002
xv
xvi
IMS Java User’s Guide
Summary of Changes |
Changes to The Current Edition of This Book for IMS Version 7
| |
This edition, which is available in softcopy format only, includes technical and editorial changes.
| |
This book has undergone major organizational changes in addition to technical changes.
| |
This book contains new information about the following enhancements to IMS Java application support: v JMP and JBP IMS dependent regions for a Java Virtual Machine (JVM) environment v DLIModel utility for creating IMS Java metadata classes v WebSphere Application Server for OS/390 and z/OS, CICS Transaction Server z/OS, and DB2 UDB for z/OS and OS/390 Stored Procedures support
| | | | | | |
Library Changes for IMS Version 7
| | | | | | | |
The major change to the IMS Version 7 library is that it is available not only in hardcopy and in softcopy on BookManager, but also in softcopy Portable Document Format (PDF). The complete library is available in BookManager and PDF on the IMS Version 7 product kit CD-ROM (LK3T-3526). The unlicensed IMS Version 7 softcopy library is available on the Transaction Processing and Data CD-ROM (SK2T-0730) and the OS/390 Collection CD-ROM (SK2T-6700) in BookManager. The unlicensed IMS Version 7 softcopy library is available in BookManager and PDF on the Web at http://www.ibm.com/ims
| | | | | | | | | | |
Other changes include changes to these following books: v IMS Version 7 Common Queue Server and Base Primitive Environment Guide and Reference The book formerly titled IMS/ESA Common Queue Server Guide and Reference in the Version 6 library is called IMS Version 7 Common Queue Server and Base Primitive Environment Guide and Reference. The IMS Version 7 Common Queue Server and Base Primitive Environment Guide and Reference is divided into two parts: ″Part 1: Common Queue Server,″ and ″Part 2: Base Primitive Environment.″ The IMS Version 7 Common Queue Server and Base Primitive Environment Guide and Reference is now an unlicensed book. v IMS Version 7 Command Reference The book formerly titled IMS/ESA Operator’s Reference in the Version 6 library is called IMS Version 7 Command Reference. v IMS Version 7 Utilities Reference: Database and Transaction Manager The books formerly titled IMS/ESA Utilities Reference: Database Manager and IMS/ESA Utilities Reference: Transaction Manager in the Version 6 library have been combined into one book called IMS Version 7 Utilities Reference: Database and Transaction Manager. v IMS Version 7 Application Programming: Database Manager and IMS Version 7 Customization Guide
| | | | | | | | | |
© Copyright IBM Corp. 2000, 2002
xvii
| | |
The chapter titled ″IMS Adapter for REXX Exit Routine″ has been moved from the IMS Version 7 Application Programming: Database Manager to the IMS Version 7 Customization Guide.
| | | |
v IMS Version 7 Sample Operating Procedures For IMS Version 7, this book is available only in BookManager and PDF softcopy on the product kit (LK3T-3526), the OS/390 Collection CD-ROM (SK2T-6700), and on the Web at: http://www.ibm.com/ims
| | |
The library includes a new book: IMS Version 7 IMS Java User’s Guide (IJUG). As a new book, the IJUG is available only in PDF and BookManager softcopy on the product kit (LK3T-3526) and on the Web at: http://www.ibm.com/ims
xviii
IMS Java User’s Guide
| |
Chapter 1. Overview of IMS Java
| | | |
IMS Java application support (hereafter called IMS Java) allows you to write Java application programs that access IMS databases from IMS, WebSphere Application Server for z/OS and OS/390, CICS Transaction Server for z/OS, or DB2 UDB for z/OS and OS/390 Stored Procedures.
| | | | | | |
IMS Java application programs use JDBC or the IMS Java hierarchic database interface. JDBC is the SQL-based standard interface for data access in the Java 2 SDK Standard Edition and Enterprise Edition. IMS Java’s implementation of JDBC supports a selected subset of the full facilities of the JDBC 2.0 API. The IMS Java hierarchic database interface is more closely related to the standard DL/I database call interface used with other languages, and provides a lower-level access to IMS database functions than the JDBC interface.
| | | |
IMS Java provides class libraries that allow you to easily develop applications that can access IMS’s broad range of database types and options, including: v Full function databases v High Availability Large Databases (HALDBs) v Fast Path Data Entry Databases (DEDBs) v Logical relationships v Secondary indexes
| | | | | | |
IMS Java application programs can be message-driven or non-message-driven and can handle a variety of message processing:
| |
v v v v
| |
Regardless of what environment the IMS Java application runs in, it accesses the IMS databases the same way.
| | | | | | | | | | | | | | |
Conversational and non-conversational transactions Multi-segment and single-segment messages Message Formatting Services (MFS) Alternate PCB program switching
Design Process 1. Determine what database information the application needs to process. 2. Create the IMS Java metadata classes based on the PSB using the DLIModel utility. The IMS database administrator, in addition to generating the PSB, also runs the DLIModel utility to create the IMS Java Metadata classes for the Java application developer to use to write the application program. 3. Write the application program. The DLIModel Java Report, generated by the DLIModel utility, provides the information about the IMS database. 4. Configure environment and deploy application.
IMS Environment Overview IMS Java application programs run in one of two IMS dependent regions, which provide a Java Virtual Machine (JVM) environment for the Java applications:
© Copyright IBM Corp. 2000, 2002
1
| | |
v Java Message Processing (JMP) region for message-driven Java applications. JMP applications process input messages from the message queue, similar to Message Processing Programs (MPPs), in a DB/DC environment.
| | | |
v Java Batch Processing (JBP) region for non-message-driven Java applications. JBP applications run in an online batch mode and do not process input messages, similar to non-message-driven Batch Message Processing (BMP) applications, in a DBCTL or a DB/DC environment.
| | |
Restrictions: v IMS Java applications cannot run in an IMS batch environment. v JBPs cannot be message driven.
| | | | |
Related Reading: v For guidance information on designing an IMS application, see IMS Version 7 Application Programming: Design Guide. v For information on configuring JMP and JBP regions, see “IMS Setup” on page 4 and IMS Version 7 Installation Volume 2: System Definition and Tailoring.
| |
WebSphere for z/OS Environment Overview
| | | | |
You can write IMS Java applications that run on a WebSphere Application Server for z/OS and OS/390 J2EE server and access IMS databases. When WebSphere for z/OS and IMS DB are on the same operating system image, the IMS Java application—a WebSphere for z/OS Enterprise Java Bean (EJB)—accesses IMS databases using the Open Database Access (ODBA) interface.
| |
Related Reading: For information on configuring WebSphere for z/OS to run IMS Java applications, see “WebSphere for z/OS Setup” on page 8.
| |
CICS Environment Overview
| |
You can write IMS Java applications that run on CICS Transaction Server for z/OS and access IMS databases.
| | |
Related Reading: v For information on configuring CICS to runs IMS Java applications, see “CICS Setup” on page 13. v For information on developing an IMS Java application that runs on a CICS Transaction Server, see “CICS Applications” on page 59.
| | | |
DB2 Environment Overview
| |
You can write DB2 UDB for z/OS and OS/390 Stored Procedures that access IMS databases.
| | | | |
Related Reading: v For information on configuring DB2 to run IMS Java applications, see “DB2 Setup” on page 15. v For information on developing an IMS Java application that runs as a DB2 stored procedure, see “DB2 Stored Procedures” on page 59.
2
IMS Java User’s Guide
Chapter 2. Setting Up Your Environment for IMS Java | | | | |
How to set up your environment to run an IMS Java application in IMS, WebSphere for z/OS, CICS, and DB2 is discussed in this chapter. The first two sections, “System Requirements for All Environments” and “General Restrictions”, apply to all environments. Environment-specific requirements and restrictions, and configuration and installation verification information is in each environment’s setup section.
| | |
In this chapter: v “System Requirements for All Environments” v “General Restrictions”
| | | | |
v v v v v
| | | | | | | | | | | | | | | | |
“IMS Setup” on page 4 “WebSphere for z/OS Setup” on page 8 “CICS Setup” on page 13 “DB2 Setup” on page 15 “DLIModel Utility Setup” on page 19
System Requirements for All Environments To use IMS Java to write application programs that access IMS databases, the following software is required: v IBM Developer Kit for OS/390, Java 2 Technology Edition with the Persistent Reusable Java Virtual Machine v OS/390 Version 2 Release 10 or higher v UNIX System Services available at runtime v Hierarchic File System (HFS) on operating system (For information on preparing HFS, see OS/390: Unix System Services File System Interface Reference) Related Reading: For systems requirements for specific environments, see: v “IMS System Requirements” on page 4 v “WebSphere for z/OS System Requirements” on page 8 v “CICS System Requirements” on page 13 v “DB2 System Requirements” on page 15
General Restrictions
| |
For all environments, IMS Java supports only the AIB interface; therefore, the database PCBs in your PSBGEN must be explicitly named.
| | | |
An IMS Java application may use path calls to access hierarchic paths of segments. Therefore, your PSBs may need to specify the P processing option for some or all segments. See Chapter 3, “Accessing an IMS Database” on page 23 for more information.
| | |
IMS does not support local transactions. Therefore, the commit, rollback, and setAutoCommit methods on an IMS Java JDBC Connection object are not supported and throw an SQLException.
| |
Related Reading: For restrictions on specific environments, see: v “IMS Restrictions” on page 4 © Copyright IBM Corp. 2000, 2002
3
v “WebSphere for z/OS Restrictions” on page 8 v “CICS Restrictions” on page 13 v “DB2 Restrictions” on page 15
| | | | |
IMS Setup This section describes the system requirements, restrictions, configuration, and installation verification specific to the IMS environment.
| | |
IMS System Requirements Java applications running in an IMS JMP or JBP region do not require any additional system requirements other than the requirements listed in “System Requirements for All Environments” on page 3.
| | | |
IMS Restrictions
|
JMP and JBP applications must be single threaded.
|
JBP applications must be non-message-driven applications.
|
JMP and JBP applications cannot access DB2 databases.
|
“General Restrictions” on page 3 lists other restrictions.
|
IMS Configuration
| |
This section gives the steps to configure JMP and JBP IMS Java dependent regions.
| | | | | | | |
Related Reading: v For detailed information on DFSJBP and DFSJMP procedures, used to start JVM dependent regions, see IMS Version 7 Installation Volume 2: System Definition and Tailoring. v For details about master JVMs and worker JVMs, and for a complete list of possible JVM options, see IBM Developer Kit for OS/390, Java 2 Technology Edition: New IBM Technology featuring Persistent Reusable Java Virtual Machines.
| | |
Configuring a JMP Region
| | | |
JVMOPMAS=member name Required parameter specifies the name of the member in IMS.PROCLIB that contains the JVM options for the master JVM. The master JVM defines the class cache for its associated worker JVMs.
To run IMS Java applications in a JMP region, the region must be initialized with specific JVM options. Specify the following parameters:
| | |
A sample member, called DFSJVMMS (master JVM options member), is supplied in the IMS sample library SDFSISRC. DFSJVMMS contains a subset of the possible JVM options.
|
This master JVM options member must contain the following JVM options:
| | | |
-Dibm.jvm.shareable.application.class.path= Specify the path names to your IMS Java application class files. Separate the path names with a colon and with no spaces. The greater-than symbol (>) acts as a nest-line extension.
4
IMS Java User’s Guide
IMS Setup | |
If your .class files are contained in a .jar file, then the absolute path name to the .jar file includes the .jar extension.
| | | |
-Dibm.jvm.trusted.middleware.class.path= Specify the path name. If using the default IMS java directory, enter /usr/lpp/ims/imsjava71/imsjava.jar. The imsjava.jar file contains the runtime libraries for IMS Java.
| | | | |
JVMOPWKR=member name Optional parameter specifies the name of the member in IMS.PROCLIB that contains the JVM options for the worker JVM. The worker JVM is created in the same address space as its master JVM. It uses the class cache defined by the master JVM.
| | | | | |
There is a sample member, called DFSJVMWK (worker JVM options member), supplied in the IMS sample library. DFSJVMWK contains a subset of the possible JVM options. ENVIRON=member name Required parameter specifies the name of a data set member that is concatenated in the PROCLIB DD.
|
Sample member DFSJVMEV is supplied in the IMS sample library SDFISRC.
| | | |
Specify the LIBPATH= environment variable in DFSJVMEV. There must be no space between the equal sign (=) in LIBPATH= and the beginning of the first path name. LIBPATH= must be set to: v The path name to the libjvm.so and libatoe.so DLLs.
| |
v The path name to the IMS V7.1 Java native C code, libJavTDLI.so. If you are using the default IMS Java directory, enter /usr/lpp/ims/imsjava71.
| | | | | | | | | |
Example: If you code ENVIRON=DFSENV on your JMP or JBP procedure, the DFSENV member must reside in IMS.PROCLIB or its equivalent. It must contain the following (comments are optional): * LIBPATH environment variable * ---------------------------* /u/oeusr02/shiraz24/J1.3/bin/classic is path to libjvm.so * /u/oeusr02/shiraz24/J1.3/bin is path to libatoe.so * /usr/lpp/ims/imsjava71 is path to libJavTDLI.so LIBPATH=/u/oeusr02/shiraz24/J1.3/bin/classic: > /u/oeusr02/shiraz24/J1.3/bin:/usr/lpp/ims/imsjava71
* * * * *
| | | |
Configuring a JBP Region
| | |
JVMOPMAS=member name For details see JVMOPMAS= for the JMP procedure under “Configuring a JMP Region” on page 4.
| | |
ENVIRON=member name For details see ENVIRON= for the JMP procedure under “Configuring a JMP Region” on page 4.
|
PROCLIB member DFSJVMAP: The member name must be DFSJVMAP.
| | |
DFSJVMAP is a member contained in a data set that is concatenated in the PROCLIB DD. A sample member, DFSJVMAP is supplied in the IMS sample library, SDFSISRC.
To run IMS Java applications in a JBP region, initialize the region with the following JVM options. Specifically, the following new procedure parameters are needed to initialize a JBP region:
Chapter 2. Setting Up Your Environment for IMS Java
5
IMS Setup Member DFSJVMAP is optional and is read during dependent region application scheduling, making it a dynamic member. You do not need to shut down IMS when adding application name mappings to DFSJVMAP for the changes to take affect. Member DFSJVMAP maps all of the 8-byte (or less), uppercase IMS Java application names that are specified to IMS to the true OMVS path name for the IMS Java application.class file.
| | | | | | |
IMS Installation Verification To verify that IMS Java is installed properly in an IMS environment: 1. Expand the file samples.tar. For instructions on expanding this file, see the Readme file in the samples directory. 2. Set the following four JVM members in IMS.PROCLIB (created at system generation), as follows: v DFSJVMAP
| | | | | | |
DFSIVP37=samples/ivp/ims/IMSIVP
DFSIVP37 is the PSB name. v DFSJVMEV
| | |
LIBPATH=/usr/lpp/J1.3/bin/classic:/usr/lpp/J1.3/bin:/usr/lpp/ims/imsjava71
/usr/lpp/ims/imsjava71 contains the native library code for IMS Java, such as libJavTDLI.so
| |
v DFSJVMMS
| | | | | | | | | | | | | | | | | | | | | | | |
-Dibm.jvm.shareable.application.class.path=> /usr/lpp/ims/imsjava71/samples.jar -Dibm.jvm.trusted.middleware.class.path=> /usr/lpp/ims/imsjava71/imsjava.jar -Xinitacsh128k -Xinitsh128k -Xmaxf0.6 -Xminf0.3 -Xmx64M -Xoss400k
v DFSJVMWK -Xmaxf0.6 -Xminf0.3 -Xmx64M -Xoss400k
3. Create HFS files JVM.out and JVM.err in the directory. 4. Submit the JCL stream to start a JMP (Java Message Processing) region. The JCL must contain the following: v Four IMS.PROCLIB members defined in step 2 v JAVAOUT and JAVAERR DD statements to allow standard output and standard errors to be sent to a file. For example: //JAVAOUT DD PATH=’/myApplication/JVM.out’ //JAVAERR DD PATH=’/myApplication/JVM.err’
Important: This procedure fails if the HFS files JVM.out and JVM.err do not exist in the specified directory. 5. From the IMS terminal, invoke the formatted screen for the transaction by issuing the following command:
| | | | |
/format IVTCM
6
IMS Java User’s Guide
IMS Setup | | | | | | | | | | | | | | | | | | | | | | | || | | | | | | | | | | | | | | | | | | | | | | | | | | || | | | |
An input screen as shown in Figure 1 is displayed. ************************************************** * IMS INSTALLATION VERIFICATION PROCEDURE * ************************************************** TRANSACTION TYPE : CONVERSATIONAL DATE : 04/03/00 PROCESS LAST FIRST
CODE
(*1) :
NAME
(*1) PROCESS CODE ADD DELETE UPDATE DISPLAY TADD END
:
NAME
:
EXTENSION
NUMBER
:
INTERNAL
ZIP CODE
:
SEGMENT# :
Figure 1. Example of a Blank IMS Installation Verification Procedure Screen
6. Enter DISPLAY for PROCESS CODE and LAST1 for LAST NAME. Figure 2 shows an example for the display query. If IMS Java is properly installed, the output shown in Figure 3 on page 8 is ************************************************** * IMS INSTALLATION VERIFICATION PROCEDURE * ************************************************** TRANSACTION TYPE : CONVERSATIONAL DATE : 04/19/00 PROCESS CODE LAST FIRST
(*1)
NAME NAME
:
DISPLAY
:
LAST1
:
EXTENSION
NUMBER
:
INTERNAL
ZIP CODE
:
(*1) PROCESS CODE ADD DELETE UPDATE DISPLAY TADD END
SEGMENT# : Figure 2. Example IMS Installation Procedure Screen with Transaction Input Information
displayed.
Chapter 2. Setting Up Your Environment for IMS Java
7
WebSphere for z/OS Setup | | | | | | | | | | | | | | | | | | | | | || | | || |
************************************************** * IMS INSTALLATION VERIFICATION PROCEDURE * ************************************************** TRANSACTION TYPE : CONVERSATIONAL DATE : 04/19/00 PROCESS LAST FIRST
CODE
(*1) :
NAME NAME
DISPLAY
:
LAST1
:
FIRST1
EXTENSION
NUMBER
:
8-111-1111
INTERNAL
ZIP CODE
:
D01/R01
Person found!
(*1) PROCESS CODE ADD DELETE UPDATE DISPLAY TADD END
SEGMENT# :
Figure 3. Example IMS Installation Verification Procedure Screen with Transaction Output Information
WebSphere for z/OS Setup
| |
This section assumes you are familiar with WebSphere Application Server for z/OS and OS/390, its Administration application, and its Application Assembly tool.
|
Related Reading:
| | | | | |
v For detailed information about how to use the Administration application, see WebSphere Application Server V4.0.1 for z/OS and OS/390 : System Management User Interface. v For detailed information about assembling and deploying an EJB onto a J2EE server, see WebSphere Application Server V4.0.1 for z/OS and OS/390 : Assembling Java 2 Platform, Enterprise Edition (J2EE) Applications.
|
WebSphere for z/OS System Requirements
| | |
Access to IMS databases from WebSphere applications requires WebSphere Application Server for z/OS and OS/390 V4.0.1 or higher and additional WebSphere Application Server z/OS Connection Management support.
|
“System Requirements for All Environments” on page 3 lists other requirements.
|
WebSphere for z/OS Restrictions The following restrictons apply to WebSphere for z/OS EJBs for accessing IMS databases: v IMS Java does not support container-managed signon or component-managed signon. v The java.sql.Connection object must be acquired, used, and closed within a transaction method.
| | | | | | | | |
v A global transaction must exist before creating a Statement or PreparedStatement object from a JDBC connection. Either specify container-demarcated transactions in the EJB deployment descriptor or explicitly
8
IMS Java User’s Guide
WebSphere for z/OS Setup | | | | | | | | | | | |
begin a global transaction by calling javax.transaction.UserTransaction.begin in the EJB method before creating a Statement or PreparedStatement object. “General Restrictions” on page 3 lists other restrictions.
WebSphere for z/OS Configuration To deploy an EJB on a WebSphere for z/OS J2EE server, you must perform the following steps: 1. Configure the WebSphere for z/OS J2EE server for access to IMS. 2. Configure the WebSphere for z/OS J2EE server to locate the IMS JDBC Resource Adapter. 3. Deploy an instance of the IMS JDBC Resource Adapter. 4. Deploy an Enterprise Archive (EAR) that contains an Enterprise Java Bean (EJB).
| | | | | |
Configuring the WebSphere for z/OS J2EE Server for IMS Access
| | |
To configure WebSphere for z/OS to access IMS databases: 1. Configure and deploy a DRA startup table.
| | |
To run an EJB on a WebSphere for z/OS J2EE server, you must configure WebSphere for z/OS to access IMS databases using ODBA. ODBA uses the database resource adapter (DRA) to access IMS databases. More details about the steps in this section are in IMS Version 7 Installation Volume 2: System Definition and Tailoring.
2. Link DRA startup table into a load library. 3. Update the JCL for the WebSphere for z/OS J2EE server on which the EJB will run by adding the load library that contains the DRA start up table and ODBA runtime code to the STEPLIB.
| | | | | | | |
Configuring the WebSphere for z/OS J2EE Server to Locate the IMS JDBC Resource Adapter
| |
Important: If you do not edit the jvm.properties file correctly, PSB allocation fails when using the IMS JDBC Resource Adapter.
| | | | | | | | | | |
To configure the WebSphere for z/OS J2EE server to locate the IMS JBDC Resource Adapter:
You must configure the WebSphere for z/OS J2EE server for the IMS JDBC Resource Adapter (also referred to as the IMS JDBC Connector). The procedure is described in this section. Activating a conversation sets the sysplex and J2EE properties for the IMS JDBC Resource Adapter. Expanding the custom service file and entering its directory in the file jvm.properties allows WebSphere for z/OS to initialize and terminate ODBA.
1. Create a conversation and define the IMS JDBC Resource Adapter as a J2EE resource: a. Open the WebSphere Application Server for z/OS and OS/390 Administration tool. b. Add a conversation. c. Navigate to the sysplex that will run the EJBs. d. Modify the sysplex properties by selecting Connection Management. e. Modify the J2EE properties by defining the CLASSPATH and LIBPATH environment variables:
Chapter 2. Setting Up Your Environment for IMS Java
9
WebSphere for z/OS Setup v For the CLASSPATH environment variable, enter the full name of the directory that contains the file imsjava.jar, including the file name. If you use the default IMS installation directory, enter /usr/lpp/ims/imsjava71/imsjava.jar v For the LIBPATH environment variable, enter the full name of where IMS Java is installed.
| | | | | | | | | | | | |
If you use the default IMS installation directory, enter /usr/lpp/ims/imsjava71 f. Save and activate the conversation. 2. In the installation directory, expand the file imsjava71.rar. If you used the default directory to install IMS, the file is in /usr/lpp/ims/imsjava71. To expand the file, enter the following command:
| | | |
The expansion puts the following files (in UTF-8 format) in the same directory as the imsjava71.rar file: v IMSJdbcCustomService.xml v howto.html
jar -xvf imsjava71.rar
| | | | | | | | | | | |
Related Reading: For more information about IMS JDBC Resource Adapter configuration, see the howto.html file. Because it is encoded in UTF-8 format, you can not read it in the OS/390 environment. To read the file, expand imsjava71.rar on your desktop. 3. Edit the jvm.properties file for WebSphere J2EE server regions that will access IMS databases to identify the location of the file IMSJdbcCustomService.xml.
| | | | | |
Deploying an Instance of the IMS JDBC Resource Adapter Configuring and deploying an instance of the IMS JDBC Resource Adapter creates a data source for an EJB. Deploy a new instance for each database or database resource adapter (DRA) startup table an EJB accesses. See “Two Strategies for Deploying Instances of IMS JDBC Resource Adaptor” on page 11 for more information on when to deploy a new instance.
| | |
Note: If you are setting up WebSphere for the first time and want to verify your installation, start the procedure in the following section “WebSphere for z/OS Installation Verification” on page 12.
| | | | | | | | | |
To deploy an instance of the IMS JDBC Resource Adapter: 1. Open the WebSphere Application Server for z/OS and OS/390 Administration tool. 2. Add a conversation. 3. Navigate to the sysplex that will run the EJBs.
To edit the jvm.properties file, add the directory where the file IMSJdbcCustomService.xml is to the preconfigured custom services in the jvm.properties file. If you use the default IMS installation directory, enter: com.ibm.websphere.preconfiguredCustomServices= /usr/lpp/ims/imsjava71/IMSJdbcCustomService.xml
The following folders are displayed: J2EEServers Servers Systems J2EE Resources
10
IMS Java User’s Guide
WebSphere for z/OS Setup | | | | | | |
Logical Resource Mapping 4. Add a J2EE resource. The resource name is your choice. The type is IMSJdbcDataSource. 5. Add a J2EE resource instance. The name is your choice. 6. Enter the DRA startup table name and optionally the DLIDatabaseView subclass name. To decide whether to add a DLIDatabaseView subclass name, see “Two Strategies for Deploying Instances of IMS JDBC Resource Adaptor”.
|
7. Save and activate the conversation.
| | | |
Note: These instructions use two conversations to deploy the IMS JDBC Resource Adapter and the Enterprise Archive (EAR). However, you can also deploy an EAR in the same conversation that deploys the IMS JDBC Resource Adapter instance.
| | |
Two Strategies for Deploying Instances of IMS JDBC Resource Adaptor: When configuring an instance of the IMS JDBC Resource Adapter, you can optionally set the DLIDatabaseView subclass name.
| | | |
If you do set the subclass name, you must create a new instance of the IMS JDBC Resource Adapter for every database an EJB accesses. You can override the DLIDatabaseView subclass name (set in step 6) in the DataSource object by calling the setDatabaseView method and providing the fully-qualified name of the subclass.
| | | |
If you do not set the subclass name, you only need to deploy an instance of the IMS JDBC Resource Adapter for each DRA startup table. In the EJB, define the DLIDatabaseView subclass name (set in step 6) in the DataSource object by calling the setDatabaseView method and providing the fully-qualified name of the subclass.
| |
Deploying an EJB onto a WebSphere for z/OS J2EE Server
| | | | | | |
To deploy your application onto the WebSphere for z/OS J2EE server: 1. Package the EJB into an Enterprise Archive (EAR) using a development tool such as Websphere Studio Application Developer Integrated Edition.
| | | | | | | | | | | | | | |
After you develop the EJB, deploy it on the WebSphere for z/OS J2EE server.
2. Import the EAR into WebSphere for z/OS and OS/390 Application Assembly tool. 3. Create a resolved EAR suitable for deploying on a WebSphere for z/OS J2EE server. 4. Open the WebSphere Application Server for z/OS and OS/390 Administration application. 5. Add a conversation. 6. Navigate to the J2EEServers folder of the sysplex that will run the EJB. The following folders are displayed: J2EEServers Servers Systems J2EE Resources Logical Resource Mapping 7. Expand the J2EEServers folder and choose the server to install the EJB on. 8. Install the EJB. a. Specify the fully-qualified directory name of the EAR and the FTP server of the sysplex where the EJB will run. b. Set the JNDI name and path. Chapter 2. Setting Up Your Environment for IMS Java
11
WebSphere for z/OS Setup c. Associate the J2EE resource defined in “Deploying an Instance of the IMS JDBC Resource Adapter” on page 10. 9. Save and activate the conversation.
| | | |
WebSphere for z/OS Installation Verification
| | | | | |
After you have configured WebSphere for z/OS to access IMS (“Configuring the WebSphere for z/OS J2EE Server for IMS Access” on page 9) and to locate the IMS JDBC Resource Adapter (“Configuring the WebSphere for z/OS J2EE Server to Locate the IMS JDBC Resource Adapter” on page 9), you can verify that your systems are configured correctly by running the installation verification program (IVP).
| | | | |
Note: You can also use this procedure to install the dealership sample EAR, which is also in samples.tar. The sample file name is imsjavaDealership.ear and the DLIDatabaseView subclass name is samples.dealership.AUTPSB11DatabaseView. 1. Transfer the IVP EAR file in binary mode to your workstation: a. Expand the samples.tar file. For instructions, see the Readme file in the samples directory. b. Use FTP to transfer the file imsjavaIVP.ear to your workstation. 2. Deploy an instance of the IMS JDBC Resource Adapter: a. Open the WebSphere Application Server for z/OS and OS/390 Administration tool. b. Add a conversation. c. Navigate to the sysplex that will run the EJBs.
| | | | | | | |
The following folders are displayed: J2EEServers Servers Systems J2EE Resources Logical Resource Mapping d. Add a J2EE resource. The resource name is your choice. The type is IMSJdbcDataSource. e. Add a J2EE resource instance with the following information: v J2EE Resource Instance Name: your choice, such as IMSJavaIVPDataSource
| | | | | | | | | | | |
v System Name: name of system that will run the server v DLIDatabaseView subclass name: samples.ivp.DFSIVP37DatabaseView
| |
v DRA Startup Table: name of your DRA table f. Save and activate the conversation. 3. Assemble the IVP EAR: a. Import the EAR into WebSphere for z/OS and OS/390 Application Assembly tool. b. Create a resolved EAR suitable for deploying on a WebSphere for z/OS J2EE server. 4. Deploy the IVP EAR, which contains the IVP JAR file and the IVP Web Archive (WAR): a. Open the WebSphere Application Server for z/OS and OS/390 Administration application. b. Add a conversation.
| | | | | | | | | | |
12
IMS Java User’s Guide
WebSphere for z/OS Setup | | | | | | | | | | | | |
c. Navigate to the J2EEServers folder of the sysplex that will run the EJB. The following folders are displayed: J2EEServers Servers Systems J2EE Resources Logical Resource Mapping d. Expand the J2EEServers folder and choose the server to install the EJB on. e. Install the EJB with the following information: v EAR file name: imsjavaIVP.ear v System name: FTP server for the sysplex that the IVP EJB will run on v JNDI Path: Clear the text field v JNDI Name: samples.ivp.was.WASIVPSessionHome
| | | | | | | | | | | |
v Associate the J2EE resource defined in step 2 on page 12. f. Save and activate the conversation. 5. Update the HTTP server to access the IVP Web application: a. Update the file webcontainer.conf to contain the context root specification for the IVP: host.default_host.contextroot=/,/IMSJdbcIVPWeb,/IMSJdbcIVPWeb/*
b. Update the file httpd.conf to contain the service entry for IVP: Service /IMSJdbcIVPWeb/*
6. Run the IVP to verify the installation: a. Open a Web browser. b. Enter the following Web address, prefaced by the specific host IP address: http://host_IP_address:8080/IMSJdbcIVPWeb/WASIVP.html
| |
CICS Setup
|
CICS System Requirements
| |
To run Java application programs in a CICS environment, you must have CICS Transaction Server for z/OS Version 2.
|
“System Requirements for All Environments” on page 3 lists other requirements.
| | | | | |
CICS Restrictions In a CICS environment, only one PSB can be allocated at a time. Therefore, an application can only have one active JDBC connection at a time. The application must close the JDBC connection before opening another JDBC connection. “General Restrictions” on page 3 lists other restrictions.
CICS Configuration
| |
To configure CICS for IMS Java, modify the CICS JVM profile DFHJVMPR. The default PDS is DFHJVM.
| | |
To configure CICS for IMS Java, modify the following in DFHJVMPR: 1. Include the IMS Java runtime libraries (imsjava.jar) as part of the CICS trusted middleware:
Chapter 2. Setting Up Your Environment for IMS Java
13
CICS Setup | | |
a. Add either a TMPREFIX or TMSUFFIX variable. The TMPREFIX adds the libraries at the head of the middleware path and TMSUFFIX adds the libraries to the end of the middleware path.
|
b. Point to the location of the IMS Java libraries.
| | | | | | | | | | |
For example, if you use the default installation directory, add the following line: TMSUFFIX=/usr/lpp/ims/imsjava71/imsjava.jar
2. Update the LIBPATH variable to contain the location of the IMS Java file libJavTDLI.so. For example, if you use the default installation directory, add the following line: LIBPATH=/usr/lpp/ims/imsjava71
3. Change the HFS dfjjvmpr.props file to set the shareable application classpath (The location of this file is specified via the JVMPROPS variable in the CICS JVM profile). Point this classpath to the locations of the user applications. For example: ibm.jvm.shareable.application.class.path=/imsjava/myApplication
Related Reading: For detailed information on CICS system definition, see CICS Transaction Server for OS/390: CICS System Definition Guide.
| | |
Installation Verification
| | |
After you configure CICS to run IMS Java applications, verify that IMS Java is installed correctly and that CICS is configured correctly to run IMS Java applications.
| | | | |
To verify the installation, install and run the CICS IVP: 1. Set the application classpath to point to samples.jar. Do this in the HFS file, dfsjjvm.props (The location of dfsjjvm.props is specified with the JVMPROPS variable in the CICS JVM profile data set member). 2. Start IMS DBCTL and CICS. 3. Turn off the upper-case translation feature. By default everything you type on the CICS terminal is converted to uppercase. However, the IVP JVM class (with the absolute path) contains lower case letters that must remain in lower case. To turn off this feature: a. On the CICS terminal, enter the transaction code CEOT NOUCTRAN. b. Press F3 to return to main CICS terminal. 4. Define a program that contains the JVM class to be run, which is CICSIVP.
| | | | | | |
a. On the CICS terminal, type CEDA DEFINE PROGRAM b. Fill in only the program name, group name, concurrency, if JVM and the JVM class.
| | | | | | | | | | | | | | |
PROGram Group COncurrency JVM JVMClass
==> cicsivp (or whatever program name you choose) ==> ivp (or whatever group name you choose) ==> Threadsafe ==> Yes ==>samples.ivp.cics.CICSIVP
c. Press F3 to return to main CICS terminal. 5. Define a transaction that can run the program and, in turn, our JVM class (such as CICSIVP). a. On the CICS terminal, type CEDA DEFINE TRANSACTION b. Fill in only the transaction, program (defined above), and group (same as program’s group):
14
IMS Java User’s Guide
CICS Setup TRANSaction ==> civp Group ==> ivp PROGram ==> cicsivp
| | | | | | | | | | | | | | | |
c. Press F3. 6. Install CICSIVP. a. On the CICS terminal, enter CEDA INSTALL b. Fill in only the program and group names: PROGram Group
=> cicsivp => ivp
c. Press F3. 7. Install the transaction civp. a. On the CICS terminal, type CEDA INSTALL b. Fill in only the transaction and group names: TRANSaction => civp Group => ivp
c. Press F3. 8. Run the transaction. a. On the CICS terminal, type civp
| | |
b. Press F3.
| |
If the transaction ran successfully, the program correctly returns a first name, last name, zip code, and extension.
| |
DB2 Setup
|
DB2 System Requirements
| | |
Access to IMS databases from DB2 Stored Procedures requires DB2 UDB for z/OS and OS/390 Version 7 with APARs PQ46673 and PQ50443. You also must have the DB2 for OS/390 and z/OS SQLJ/JDBC driver with APAR PQ48383 installed.
|
“System Requirements for All Environments” on page 3 lists other requirements.
|
DB2 Restrictions
| | | |
In a WLM-managed stored procedure address space configured to run LANGUAGE JAVA stored procedures, a considerable amount of storage is used for the Java Virtual Machine. The NUMTCB parameter must be adjusted accordingly. The recommended NUMTCB is a maximum of 7.
|
“General Restrictions” on page 3 lists other restrictions.
|
DB2 Configuration
|
The stored procedures must be compiled (javac) by JDK 1.3.1.
| | | | | | | | |
The following is an example JCL procedure of a Java WLM-established address space: //V71AWLM1 PROC RGN=0M,APPLENV=application_environt_name, // DB2SSN=your_db2-subsystem-name,NUMTCB=7 //IEFPROC EXEC PGM=DSNX9WLM,REGION=&RGN,TIME=NOLIMIT, // PARM=’&DB2SSN,&NUMTCB,&APPLENV’ //STEPLIB DD DISP=SHR,DSN=CEE.SCEERUN //* DB2 Library // DD DISP=SHR,DSN=yourDB2HLQ.SDSNLOAD Chapter 2. Setting Up Your Environment for IMS Java
15
DB2 Setup | | | | | | | | | | | |
// DD DISP=SHR,DSN=yourDB2HLQ.SDSNLOD2 // DD DISP=SHR,DSN=yourDB2HLQ.RUNLIB.LOAD //* DBRM library // DD DISP=SHR,DSN=yourHLQ.SDSNDBRM //* ODBA Interface //DFSRESLB DD DISP=SHR,DSN=yourHLQ.HRESLIB // DD DISP=SHR,DSN=yourHLQ.TNUC0 //JAVAENV DD DISP=SHR,DSN=yourHLQ.JAVAENV //JSPDEBUG DD SYSOUT=* //CEEDUMP DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=*
| | | | | |
Notes: 1. For general purpose use, the first card could be:
| |
ENVAR Settings for the JAVAENV Data Set
| |
JAVA_HOME= HFS directory where the required JVM is installed
| |
DB2_HOME= HFS directory where the DB2 for OS/390 JDBC/SQLJ driver is installed
| | | |
CLASSPATH= can optionally be specified. If CLASSPATH= is specified, it is the path of HFS directories that is searched for Java class files when the stored procedures definition does not specify a JAR
| |
LIBPATH= HFS directory where libJavTDLI.so resides
| | | |
TMSUFFIX= Full path of HFS directory where imsjava.jar is located. If using the default IMS Java directory, specify:
| | | | |
The JAVAENV data set should have the following attributes:
| | | | | |
For example:
| | | | | |
The following is an example of JCL to define your stored procedure to SYSIBM.SYSROUTINES:
//V71AWLM1 PROC RGN=0M,APPLENV=,DB2SSN=,NUMTCB=
2. The PROC name (V71AWLM) must be defined in the RACF started procedure table 3. Your HLQ.TNUC0 is a data set that contains the DRA start-up table The JAVAENV data set must include the following ENVAR settings:
TMSUFFIX=/usr/lpp/ims/imsjava71/imsjava.jar
Organization Record format Record length Block size .
. . . .
. . . .
. . . .
: : : :
PS VB 1028 6144
ENVAR("CLASSPATH=/imsjava", "DB2_HOME=/usr/lpp/db2/dev710", "JAVA_HOME=/usr/lpp/java/J1.3", "LIBPATH=/usr/lpp/ims/imsjava71", "TMSUFFIX=/usr/lpp/ims/imsjava71/imsjava.jar)
//CREATJSP // // //
16
IMS Java User’s Guide
JOB ,’YOUR NAME’, MSGCLASS=H,TIME=3, USER=SYSADM,PASSWORD=XXXXXXXX, MSGLEVEL=(1)
DB2 Setup | | | | | | | | | | | | | | | | | | | | | | | | | | |
//************************************************************* //* Change xx in the PLAN(DSNTIAxx) to your DB2 Version //* such as 71 or 81 //************************************************************* //CREATJSP EXEC PGM=IKJEFT01,DYNAMNBR=20 //STEPLIB DD DISP=SHR,DSN=DB2HLQ.DSNEXIT // DD DISP=SHR,DSN=DB2HLQ.SDSNLOAD //SYSTSPRT DD SYSOUT=* //SYSTSIN DD * DSN SYSTEM(your_db2_subsystem_name) RUN PROGRAM(DSNTIAD) PLAN(DSNTIAxx) LIB(’DB2HLQ.RUNLIB.LOAD’) PARM(’RC0’) //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * CREATE PROCEDURE yourJavaStoredProcedureName(VARCHAR(20) IN, VARCHAR(1000) OUT) FENCED NO SQL LANGUAGE JAVA DYNAMIC RESULT SET 0 EXTERNAL NAME ’packageName.ClassName.methodEntryName’ PARAMETER STYLE JAVA COLLID DSNJDBC WLM ENVIRONMENT your_WLM_Environment_Name; GRANT EXECUTE ON PROCEDURE yourJavaStoredProcedureName TO PUBLIC;
| | | | | | | | | | | | | | | | | | | | | | |
The following is a sample JCL to delete your stored procedure from SYSIBM.SYSROUTINES:
|
//DELETJSP JOB ,’YOUR NAME’, // MSGCLASS=H,TIME=3,USER=SYSADM,PASSWORD=XXXXXXXX, // MSGLEVEL=(1) //************************************************************* //* Change xx in the PLAN(DSNTIAxx) to your DB2 version, //* such as 71 or 81 //************************************************************** //JOBLIB DD DISP=SHR,DSN=CEE.SCEERUN // DD DISP=SHR,DSN=DB2HLQ.DSNEXIT // DD DISP=SHR,DSN=DB2HLQ.SDSNLOAD //PH061S01 EXEC PGM=IKJEFT01,DYNAMNBR=20 //SYSTSPRT DD SYSOUT=* //SYSTSIN DD * DSN SYSTEM(your_DB2_subsystem_name) RUN PROGRAM(DSNTIAD) PLAN(DSNTIA71) LIB(’DB2HLQ.RUNLIB.LOAD’) PARM(’RC0’) //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * DROP PROCDURE yourJavaStoredProcedureName RESTRICT;
DB2 Installation Verification
| |
The following is sample code of the DB2 Client and DB2 Stored Procedure classes for the DB2 installation verification program.
| |
These classes can be found in the samples.tar file (by default in the /usr/lpp/ims/imsjava71/samples directory).
| | | |
To verify that DB2 is configured correctly and that IMS Java is installed correctly: 1. Set CLASSPATH in JAVAENV data set to samples.jar (default is /usr/lpp/ims/imsjava71/samples.jar) 2. Submit the following JCL to define the stored procedure to DB2: Chapter 2. Setting Up Your Environment for IMS Java
17
DB2 Setup //CREATIVP JOB ,’YOUR NAME’, // MSGCLASS=H,TIME=3, // USER=SYSADM,PASSWORD=XXXXXXXX, // MSGLEVEL=(1) //****************************************************************************** //* Change xx in the PLAN(DSNTIAxx) to your DB2 version //* such as: 71 or 81 //****************************************************************************** //CREATJSP EXEC PGM=IKJEFT01,DYNAMNBR=20 //STEPLIB DD DISP=SHR,DSN=DB2HLQ.DSNEXIT // DD DISP=SHR,DSN=DB2HLQ.SDSNLOAD //SYSTSPRT DD SYSOUT=* //SYSTSIN DD * DSN SYSTEM(DB2_Subsystem_Name) RUN PROGRAM(DSNTIAD) PLAN(DSNTIAxx) LIB(’DB2HLQ.RUNLIB.LOAD’) PARM(’RC0’) //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * CREATE PROCEDURE IVPStoredProc(VARCHAR (50) IN, VARCHAR (200) OUT,VARCHAR(500) OUT) FENCED NO SQL LANGUAGE JAVA DYNAMIC RESULT SET 0 EXTERNAL NAME ’samples.ivp.db2.DB2IvpStoredProcedure.execute’ PARAMETER STYLE JAVA COLLID DSNJDBC WLM ENVIRONMENT Your_WLM_Environment_Name; GRANT EXECUTE ON PROCEDURE IVPStoredProc TO PUBLIC;
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
3. Submit the following JCL to create a plan for the client program: //BNDIVPCL JOB ,’YOUR NAME’, // MSGCLASS=H,TIME=3, // USER=SYSADM,PASSWORD=XXXXXXXX, // MSGLEVEL=(1) //********************************************************************* //* Change xx in the PLAN(DSNTEPxx) to your DB2 version //* such as: 71 or 81 //********************************************************************* //BINDCLNT EXEC PGM=IKJEFT01,DYNAMNBR=20 //STEPLIB DD DISP=SHR,DSN=DB2HLQ.DSNEXIT // DD DISP=SHR,DSN=DB2HLQ.SDSNLOAD //DBRMLIB DD DISP=SHR,DSN=DB2HLQ.SDSNDBRM //SYSTSPRT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSTSIN DD * DSN SYSTEM(DB2ID) BIND PACKAGE (DSNJDBC) MEMBER(DSNJDBC1) ISOLATION(UR) ACTION(REPLACE) VALIDATE(BIND) BIND PACKAGE (DSNJDBC) MEMBER(DSNJDBC2) ISOLATION(CS) ACTION(REPLACE) VALIDATE(BIND) BIND PACKAGE (DSNJDBC) MEMBER(DSNJDBC3) ISOLATION(RS) ACTION(REPLACE) VALIDATE(BIND) BIND PACKAGE (DSNJDBC) MEMBER(DSNJDBC4) ISOLATION(RR) ACTION(REPLACE) VALIDATE(BIND) BIND PLAN(DB2IVPCL) KEEPDYNAMIC(YES) ACTION(REPLACE) PKLIST(DSNJDBC.DSNJDBC1, DSNJDBC.DSNJDBC2, DSNJDBC.DSNJDBC3, DSNJDBC.DSNJDBC4) RUN PROGRAM(DSNTEP2) PLAN(DSNTEPxx) LIB(’DB2HLQ.RUNLIB.LOAD’) END
18
IMS Java User’s Guide
DB2 Setup | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
//SYSIN DD * GRANT EXECUTE ON PLAN DB2IVPCL TO PUBLIC; /* //
4. For USS, create a file named db2sqljjdbc.properties that contains the following: DB2SQLJSSID=yourDB2ID DB2SQLJPLANNAME=DB2IVPCL DB2SQLJATTACHTYPE=RRSAF DB2SQLJDBRMLIB=DB2HLQ.SDSNDBRM
The location of this file is pointed to by the environment variable DB2SQLJPROPERTIES. 5. Set environment variables in USS. For example: export SQLJ_HOME=location of your SQLJ driver (for example /usr/lpp/db2/db2710) export JDBC_HOME=location of your JDBC driver (for example /usr/lpp/db2/db2710) export JAVA_HOME=location of your JDK1.3 (for example /usr/lpp/java/J1.3) export DB2SQLJPROPERTIES=/imsjava/jdbclinks/db2sqljjdbc.properties export export export export export
CLASSPATH=$JDBC_HOME/classes/db2jdbcclasses.zip CLASSPATH=$CLASSPATH:$SQLJ_HOME/classes/db2sqljruntime.zip CLASSPATH=$CLASSPATH:$SQLJ_HOME/classes/db2sqljclasses.zip CLASSPATH=$CLASSPATH:/usr/lpp/ims/imsjava71/imsjava.jar CLASSPATH=$CLASSPATH:$JAVA_HOME/lib:.
export LIBPATH=$SQLJ_HOME/lib:$JDBC_HOME/lib export LIBPATH=:$JAVA_HOME/lib:$LIBPATH export LD_LIBRARY_PATH=.:$SQLJ_HOME/bin:$JDBC_HOME/lib export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$JAVA_HOME/lib export PATH=$SQLJ_HOME/bin:$PATH export STEPLIB=yourDB2HLQ.DSNEXIT:yourDB2HLQ.SDSNLOAD: export STEPLIB=yourDB2HLQ.SDSNLOD2:yourDB2HLQ.SDSNLINK:$STEPLIB
6. Issue the following command at the USS prompt while you are in /usr/lpp/ims/imsjava71: java samples.ivp.db2.DB2IvpClient yourDRAname
If the program ran sucessfully, it will display a first name, last name, extension, and zip code.
DLIModel Utility Setup Before the DLIModel utility can be run, from the MVS USS prompt or by running JCL, some preparation is required. Since DLIModel is a Java application, this preparation depends on the Java environment in your installation. Guidelines are provided here, but they may require modification in order to fit your environment.
Preparing the DLIMODEL MVS Procedure The DLIMODEL procedure is delivered as member DFSMODEL in the IMS distribution library SDFSISRC. To prepare this procedure, perform the following steps: 1. Decide how you want to make the required .jar files available to the procedure. The procedure needs the following .jar files (found in the distribution directory /usr/lpp/ims/imsjava71/dlimodel): dlimodel.jar Chapter 2. Setting Up Your Environment for IMS Java
19
DLIModel Utility Setup mofrt.jar xerces.jar ctccobol.jar tdlang.jar
| | | | | | |
The recommended way is to include the files in the appropriate CLASSPATH environment variable for the utility’s runtime environment before running the procedure.
| | | | | | |
If you do not want to change the CLASSPATH environment variable, you can use the -cp option of the java command in step 5 2. Copy the member DFSMODEL from its distribution library SDFSISRC to the PROCLIB from where your installation submits IMS procedures for batch execution. 3. Rename the procedure, if desired. This book assumes that you have renamed it DLIMODEL.
| | | | | | |
4. Determine if you need to create a script file. The script file is an HFS file with a single-line Java command that runs the DLIModel utility (a Java application). The file is referenced in the PARM field in the EXEC statement. You need a script file if the command—including the path and file name of the control data set—exceeds the 100-byte limit. You do not need a script file if you do not exceed the limit and if you tailor the procedure by placing the java command directly in the PARM field.
| | |
5. If needed, create an HFS script file with the java command. (If you do not need the script file, use the same syntax as follows for the command in the PARM field.) In the HFS script file, write a single-line command using the following syntax:
|
(1)
| QQ java
(2) com.ibm.ims.metagen.DLIModel
“$1”
PDS
QT
| |
Notes:
| | |
1
The simple form assumes that the java command is accessible through your PATH envirnoment variable and that the CLASSPATH environment variable includes all necessary .jar files.
| |
2
The $ symbol can vary by locale, so you use the valid value for your USS setup.
| |
com.ibm.ims.metagen.DLIModel Main class of this DLIModel utility.
| | | | |
″$1″ Symbolic parameter that takes the value of the data set name of the utility control statement data set. This symbolic parameter is set from the DSNAME parameter in the EXEC statement that runs the DLIMODEL procedure.
| |
PDS Required parameter is a string literal.
| | | |
If your environment variables are not set as described previously (for example, you are running the utility on an experimental or trial basis), you can use the following syntax for the command (the single line command has been wrapped to fit the page):
20
IMS Java User’s Guide
DLIModel Utility Setup | | |
/path/java -cp /path/dlimodel.jar: /path/mofrt.jar:/path/xerces.jar:/path/ctccobol.jar: /path/tdlang.jar com.ibm.ims.metagen.DLIModel "$1" PDS
| |
/path/java Identifies the JDK 1.3 java command through an explicit path.
| | | |
-cp /path/dlimodel.jar:/path/mofrt.jar:/path/xerces.jar: /path/ctccobol.jar:/path/tdlang.jar Provides a classpath environment for this Java execution. It contains the .jar files required by the utility.
| | | | | | |
Related Reading: For more information about the MVS BPXBATCH utility, see OS/390: Unix Systems Services User’s Guide and OS/390: Unix Systems Services Command Reference. 6. If you used a script file, reference the file in the PARM field of the EXEC statement in the DLIMODEL procedure. As provided, the PARM field references /usr/lpp/ims/imsjava71/dlimodel/go.
Preparing to Run From the MVS USS Prompt
| | | | | | | | | | | |
To run the DLIModel utility from the MVS USS prompt, perform the following steps: 1. Ensure that the following required execution-time .jar files are present in the CLASSPATH environment variable of your shell: dlimodel.jar mofrt.jar xerces.jar ctccobol.jar tdlang.jar 2. Ensure that your PATH environment variable is set so that the JDK 1.3 ″java″ command is accessible. 3. Issue the simple form of the command in the step 5 on page 20 in the previous section.
| |
Alternately, you can add a path prefix to the java command and use the -cp option of the java command, as described in step 5 on page 20 in the previous section.
Chapter 2. Setting Up Your Environment for IMS Java
21
DLIModel Utility Setup
22
IMS Java User’s Guide
| |
Chapter 3. Accessing an IMS Database
|
IMS Java supports two styles of database programming:
| | | |
JDBC JDBC is the SQL-based standard interface for data access in the Java 2 SDK Standard Edition and Enterprise Edition. IMS Java’s implementation of JDBC supports a selected subset of the full facilities of the JDBC 2.0 API. This is the recommended style where sufficient for the application.
| | | | | | | |
IMS Java hierarchic database interface The IMS Java hierarchic database interface is more closely related to the standard DL/I database call interface used with other languages, and provides a lower-level access to IMS database functions than the JDBC interface. Using this style of programming, you can build segment search arguments (SSAs) and call the functions of the DLIConnection object to read, insert, update, or delete segments. With this style, the application has full control to navigate the segment hierarchy.
| | |
Note: Both styles require that you first describe your IMS databases to the IMS Java classes through a metadata class, as described below under “Describing Your IMS Databases to IMS Java” on page 24.
| |
Recommendation: Before accessing an IMS database, you should have a basic understanding of hierarchical databases.
| | |
This chapter uses the sample applications shipped with IMS Java to show how to access IMS database. For information on expanding and locating these files, see the Readme file in the samples directory.
| | | | |
All samples use a car dealership example and use JDBC for database processing. All samples process a common set of databases, and the jobs to define and load these databases are contained in the directory samples/dealership/databases. For information on how to run the database definition and load jobs, see the IMS sample Readme file in the directory samples/dealership/ims/Readme.
| | |
Related Reading: For a full specification of the classes used in this chapter, see the JavaDoc shipped with IMS Java. If using the default installation directory, the JavaDoc is in directory usr/lpp/ims/imsjava71/docs/.
| |
Introduction to the Example Environment
| | | | | |
In this chapter and in Chapter 4, “Writing a Java Application Program” on page 45, a sample application program is introduced. The sample program uses an automobile dealership program for illustration purposes. This and other automobile dealership applications are available in the samples.tar file shipped with the IMS Java product (See the Readme file in the samples directory for instructions on how to expand and access these sample applications).
| | | | | | |
The sample database contains five segment types. The root segment is the Dealer segment. Its child segment is the Model segment. Under the Model segment are its children: the segments Order, Stock, and Sales. This is the same database example that will be used in Chapter 3, “Accessing an IMS Database”, and in “Example 4. Example with Multiple Control Statements” on page 85. See Figure 6 on page 25 for the DBD of this database.
© Copyright IBM Corp. 2000, 2002
23
|
| | | | |
Figure 4. Example Database Hierarchy
The Dealer segment identifies a dealer selling cars. The segment contains a unique dealer number, dealer name and address, and annual sales information.
| | |
Dealers carry car types, each of which has a corresponding Model segment. A Model segment contains a unique type code, descriptive information about the car, and its price.
| | | | |
There is an Order segment for each car ordered for the dealership. The segment is sequenced by an order number that contains information about the options, pricing, order date, and the customer who ordered the car. When a car is delivered to fill a particular order, its serial number and delivery date are added to the segment. The segment is deleted when the customer (or dealer) accepts the car.
| | | | |
A Stock segment is created for each car that is available for sale in the dealer’s inventory. The segment is sequenced by a serial number that is unique to a given model. It contains descriptive information about the car and the date it was delivered to the dealer. The segment remains in the database until the car is sold from stock.
| | |
Finally, when the car is sold, a Sales segment is created. This segment is sequenced by sale date and contains information about the car sold and the purchaser.
| |
JDBC Access Method
|
Describing Your IMS Databases to IMS Java
| | | |
Processing a set of IMS databases by an IMS Java application using JDBC requires that you describe to IMS Java the database view of your application’s PSB. You do this by providing the name of a metadata class when establishing the JDBC database connection.
| | | | |
There are two ways you can prepare the metadata class for a PSB: v Provide the application PSB source and any related DBD source to the DLIModel utility, and specify the generation of the IMS Java metadata class. This is the recommended technique and is described in Chapter 5, “DLIModel Utility” on page 61.
24
IMS Java User’s Guide
JDBC Access Method | |
v Code the metadata class manually. This is described in Appendix A, “Manually Creating IMS Java Metadata Classes” on page 99.
| |
This chapter assumes that you have prepared a metadata class by using the DLIModel utility.
| | | | | | | | | | | | |
The examples used for the rest of this chapter are based on the following simple application. The PSB for the application is as shown in Figure 5. This database is the Automobile Dealership database that was introduced in “Introduction to the Example Environment” on page 23.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
DLR_PCB1 PCB TYPE=DB,DBDNAME=DEALERDB,PROCOPT=GO,KEYLEN=42 SENSEG NAME=DEALER,PARENT=0 SENSEG NAME=MODEL,PARENT=DEALER SENSEG NAME=ORDER,PARENT=MODEL SENSEG NAME=SALES,PARENT=MODEL SENSEG NAME=STOCK,PARENT=MODEL PSBGEN PSBNAME=DLR_PSB,MAXQ=200 END
Figure 5. Example PSB Definition
The physical DBD referenced by this PSB is shown in Figure 6. DBD NAME=DEALERDB,ACCESS=(HDAM,OSAM),RMNAME=(DFSHDC40.1.10) SEGM NAME=DEALER,PARENT=0,BYTES=94, FIELD NAME=(DLRNO,SEQ,U),BYTES=4,START=1,TYPE=C FIELD NAME=DLRNAME,BYTES=30,START=5,TYPE=C SEGM NAME=MODEL,PARENT=DEALER,BYTES=43 FIELD NAME=(MODTYPE,SEQ,U),BYTES=2,START=1,TYPE=C FIELD NAME=MAKE,BYTES=10,START=3,TYPE=C FIELD NAME=MODEL,BYTES=10,START=13,TYPE=C FIELD NAME=YEAR,BYTES=4,START=23,TYPE=C FIELD NAME=MSRP,BYTES=5,START=27,TYPE=P SEGM NAME=ORDER,PARENT=MODEL,BYTES=127 FIELD NAME=(ORDNBR,SEQ,U),BYTES=6,START=1,TYPE=C FIELD NAME=LASTNME,BYTES=25,START=50,TYPE=C FIELD NAME=FIRSTNME,BYTES=25,START=75,TYPE=C SEGM NAME=SALES,PARENT=MODEL,BYTES=113 FIELD NAME=(SALDATE,SEQ,U),BYTES=8,START=1,TYPE=C FIELD NAME=LASTNME,BYTES=25,START=9,TYPE=C FIELD NAME=FIRSTNME,BYTES=25,START=34,TYPE=C FIELD NAME=STKVIN,BYTES=20,START=94,TYPE=C SEGM NAME=STOCK,PARENT=MODEL,BYTES=62 FIELD NAME=(STKVIN,SEQ,U),BYTES=20,START=1,TYPE=C FIELD NAME=COLOR,BYTES=10,START=37,TYPE=C FIELD NAME=PRICE,BYTES=5,START=47,TYPE=C FIELD NAME=LOT,BYTES=10,START=52,TYPE=C DBDGEN FINISH END
Figure 6. DBD Sample Definition
The DLIModel utility produces a DLIModel Java Report of its generated metadata structure. For an example of the report produced by DLIModel see Figure 7 on page 26.
Chapter 3. Accessing an IMS Database
25
JDBC Access Method | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
DLIModel Java Report ======================== Class: DealerDatabaseView in package: com.ibm.ims.tooling generated for PSB: DLR_PSB ================================================== PCB: DealershipDB ================================================== Segment: DEALER Field: DealerNumber Type=CHAR Start=1 Length=4 ++ Primary Key Field ++ Field: DealerName Type=CHAR Start=5 Length=30 Field: DealerAddress Type=CHAR Start=35 Length=50 Field: YTDSales Type=PACKEDDECIMAL Type Qualifier=S9(18) Start=85 Length=10 ================================================== Segment: MODEL Field: ModelTypeCode Type=CHAR Start=1 Length=2 ++ Primary Key Field ++ Field: CarMake Type=CHAR Start=3 Length=10 (Search Field) Field: CarModel Type=CHAR Start=13 Length=10 (Search Field) Field: CarYear Type=CHAR Start=23 Length=4 (Search Field) Field: Price Type=CHAR Start=27 Length=5 (Search Field) Field: EPACityMilage Type=CHAR Start=32 Length=4 Field: EPAHighwayMilage Type=CHAR Start=36 Length=4 Field: Horsepower Type=CHAR Start=40 Length=4 ================================================== Segment: ORDER Field: OrderNumber Type=CHAR Start=1 Length=6 ++ Primary Key Field ++ Field: PurchaserLastName Type=CHAR Start=50 Length=25 (Search Field) Field: PurchaserFirstName Type=CHAR Start=75 Length=25 (Search Field) Field: Options Type=CHAR Start=7 Length=30 Field: Price Type=ZONEDDECIMAL Type Qualifier=99999 Start=37 Length=5 Field: OrderDate Type=CHAR Start=42 Length=8 Field: SerialNo Type=CHAR Start=100 Length=8 Field: DeliverDate Type=CHAR Start=120 Length=8 ================================================== Segment: SALES Field: DateSold Type=CHAR Start=1 Length=8 ++ Primary Key Field ++ Field: PurchaserLastName Type=CHAR Start=9 Length=25 (Search Field) Field: PurchasetFirstName Type=CHAR Start=34 Length=25 (Search Field) Field: StockVINumber Type=CHAR Start=94 Length=20 (Search Field) Field: PurchaserAddress Type=CHAR Start=59 Length=25 Field: SoldBy Type=CHAR Start=84 Length=10 ================================================== Segment: STOCK Field: StockVINumber Type=CHAR Start=1 Length=20 ++ Primary Key Field ++ Field: Color Type=CHAR Start=37 Length=10 (Search Field) Field: Price Type=ZONEDDECIMAL Type Qualifier=99999 Start=47 Length=5 Field: Lot Type=CHAR Start=53 Length=10 (Search Field) Field: DateIn Type=CHAR Start=21 Length=8 Field: DateOut Type=CHAR Start=29 Length=8
| | Figure 7. The IMS Java Summary Report | The DLIModel Summary Report provides you with the following information: | v The name of the metadata class (DealerDatabaseView), to use when you | establish a connection to the database. | v The hierarchy of segments in each PCB view. | v The fields within each segment. These will include the fields specified in the | DBD, but also include additional fields specified to DLIModel based (for example) | on field layouts of segments in existing applications. For example, the fields | DealerAddress and YTDSales in the Dealer segment are added fields. | v The names of PCBs, segments, and fields to use in your JDBC calls. These | names may be alias names assigned to the IMS entities. Alias names are | intended to be more representative and intuitive identifiers for your Java |
26
IMS Java User’s Guide
JDBC Access Method | | | | | | | | | | | | | | | |
application to use rather than the 8-character names in the IMS PSBs and DBDs. In the example the name, DealershipDB replaces the PCB name DLR_PCB1 from the PSB. And a comparison of the names of the segments and the fields in the report with their names in the DBD shows that they have all been assigned more meaningful names. v Data types of fields. The data types of the fields are also based on information supplied to the utility, and supplement the simple TYPE property of fields in the DBD. For example, the field YTDSales in Dealer is described as type PACKEDDECIMAL with a Type Qualifier (format descriptor) of S9(18). v Fields in each segment, identified as primary or secondary index fields, search fields, or other fields. Generally, predicates in WHERE clauses that are based on index fields provide the fastest response. However, predicates may be qualified on search fields if necessary. Predicates may not be qualified on other fields. For example, in segment, Dealer, a search predicate is best qualified on DealerNumber, may be qualified on DealerName if desired, but may not be qualified on DealerAddress or YTDsales.
| | | |
The report is intended to be a sufficient source of information on your data for you to code JDBC calls and write your application. It should not be necessary for you to refer to the generated metadata class, nor to examine the original PSB and DBD source files.
| |
Related Reading: For details of the DLIModel Java Report and its contents, see “DLIModel Java Report” on page 64.
|
Using JDBC to Access an IMS Database
|
This section discusses accessing IMS databases using JDBC.
| | | | | | | | |
Classes and Field Names A database segment definition defines the fields for a set of segment instances similar to the way a relational table defines columns for a set of rows in a table. In this regard, segments relate to tables, and fields in a segment relate to columns in a table as illustrated in Figure 8 on page 28 Similarly, an instance of a segment in a database corresponds to a row (or tuple) in a table. Note that if a segment does not have a unique key the corresponding relational table should be viewed as having a generated unique key added to its column (field) list.
Chapter 3. Accessing an IMS Database
27
JDBC Access Method |
| | | | | | | | |
Figure 8. IMS DB Segments and Fields with Their Corresponding DB2 Tables and Columns
For the purpose of writing JDBC calls, a database segment definition defines the fields for a set of segment instances similar to the way a relational table defines columns for a set of rows in a table. In this way, segments relate to tables, and fields in a segment relate to columns in a table. And so, the name of an IMS segment from the summary report becomes the table name in an SQL query, and the name of a field becomes the column name in the query.
| | |
For example, in the query below, Model is a segment name that is used as a table name in the query:
| | |
In the following example, ModelTypeCode is the name of a field contained in the Model segment and it is used in the SQL query as a column name:
| | | | | |
In both of the preceding examples, Model and ModelTypeCode are alias names assigned by using the DLIModel utility. These names will likely not be the same eight character names used in the database definition for IMS. Alias names are described in further detail in Chapter 5, “DLIModel Utility” on page 61 and aliases simply act as references to the eight character names described in the IMS DBD (database definition).
| | | | | | |
PCB-Qualifying SQL Queries
SELECT * FROM Model
SELECT * FROM Model WHERE ModelTypeCode = ’K1’
In IMS Java Connections are made to PSBs. Therefore, there must be a way to specify which PCB to use when executing an SQL query on the Connection. To do this, segments referenced in the FROM clause of an SQL statement should always be PCB qualified. The one exception to this rule is if the PSB contains only one PCB, in which case the PCB name can be omitted. Here is an example:
28
IMS Java User’s Guide
JDBC Access Method | SELECT * | FROM DealershipDB.Model | | Figure 9. PCB-Qualifying SQL Query Example
|
Recommendation: For coding clarity and performance reasons, segments in the FROM clause should always be PCB qualified, even when not required (unless readability is seriously sacrificed).
Writing an Application that Uses JDBC To use JDBC to read, update, insert, and delete segment instances, an application must: 1. Load the DLIDriver and retrieve a Connection object from the DriverManager. This step is highlighted in bold text in Figure 10 on page 30. 2. Retrieve a Statement or PreparedStatement object from the Connection and execute it. For an example, see “SELECT” on page 35. 3. Iterate the ResultSet returned from the Statement or PreparedStatement object to retrieve specific field results. For an example, see “SELECT” on page 35. Figure 10 on page 30 builds on the sample program described in “Building an IMS Java Application by Example” on page 46, starting from step 1 above. | | | | |
To use abbreviated class names (instead of fully-qualified names) in your program, include import statements at the top of the Java file. Use the following import statement to make IMS database access classes available by their unqualified class names: import com.ibm.ims.db.*;
| | |
Use the following import statement to make JDBC classes available by their unqualified class names:
| | |
When using JDBC to access an IMS database, an application programmer provides the name of the DLIDatabaseView subclass when getting a JDBC Connection object.
| | |
When the following line from Figure 10 on page 30 is executed, DLIDriver, a class in com.ibm.ims.db, registers itself with the JDBC DriverManager:
| | | | |
When the following line from Figure 10 on page 30 is executed, the JDBC DriverManager determines which of the registered drivers supports the supplied string.
| | |
In this case, because the supplied string begins with jdbc:dli:, JDBC DriverManager locates the DLIDriver instance and requests that it create a connection.
import java.sql.*;
Class.forName("com.ibm.ims.db.DLIDriver");
connection = DriverManager.getConnection ("jdbc:dli:dealership.application.DealerDatabaseView");
Chapter 3. Accessing an IMS Database
29
JDBC Access Method package dealership.application; import com.ibm.ims.base.*; import com.ibm.ims.application.*; import com.ibm.ims.db.*; import java.sql.*;
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
public class IMSAuto extends IMSApplication { IMSMessageQueue messageQueue = null; InputMessage inputMessage = null; ModelOutput modelOutput = null; Connection connection = null; public IMSAuto() { super(); } public static void main(String args[]){ IMSAuto imsauto = new IMSAuto(); imsauto.begin(); } public void doBegin() throws IMSException { messageQueue = new IMSMessageQueue(); inputMessage = new InputMessage(); modelOutput = new ModelOutput(); try { Class.forName("com.ibm.ims.db.DLIDriver"); connection = DriverManager.getConnection ("jdbc:dli:dealership.application.DealerDatabaseView"); } catch (Exception e){ reply("Connection not established"); } while(messageQueue.getUniqueMessage(inputMessage)) { if (!inputMessage.getString("ModelTypeCode").trim().equals("")){ if (getModelDetails(inputMessage, modelOutput)) messageQueue.insertMessage(modelOutput); } else { reply("Invalid Input"); }
}
}
| | | | | |
}
IMSTransaction.getTransaction().commit();
public void reply(String errmsg) throws IMSException{ ErrorMessage errorMessage = new ErrorMessage(); errorMessage.setString("MessageText",errmsg); messageQueue.insertMessage(errorMessage); }
Figure 10. JDBC Application
The following list describes the JDBC 2.1 required interfaces that are implemented in the database package, including limitations in the DL/I implementation of these interfaces. java.sql.Connection java.sql.Connection is an object that represents the connection to the
| |
30
IMS Java User’s Guide
JDBC Access Method | | | | |
database. A Connection reference is retrieved from the DriverManager object implemented in the java.sql package. The DriverManager obtains a Connection reference by querying its list of registered Driver instances until it finds one that supports the universal resource locator (URL) passed to DriverManager.getConnection.
| | | |
Restriction: IMS does not support the local, connection-based commit scope defined in the JDBC model. Therefore, the DL/I implementation of Connection.commit, Connection.rollback, and Connection.setAutoCommit results in an SQLException when called from a client program.
| | | |
Figure 11 illustrates the code to establish a connection to the database:
| | | | | | | | | | | | | | |
connection = DriverManager.getConnection ("jdbc:dli:dealership.application.DealerDatabaseView");
Figure 11. Establish a Database Connection
java.sql.DatabaseMetaData DatabaseMetaData defines a set of methods to query information about the database, including capabilities the database might or might not support. The class is provided for tool developers and is normally not used in client programs. Much of the functionality is specific to relational databases and is not implemented for DL/I databases. java.sql.Driver The Driver interface itself is not usually used in client programs, although an application needs to dynamically load a particular Driver implementation by name. One of the first lines in an IMS JDBC program for DL/I access must be: Class.forName("com.ibm.ims.db.DLIDriver");
| | | | | |
This code loads the Driver and causes the Driver implementation to register itself with the DriverManager so that the driver can later be found by DriverManager.getConnection. The Driver implementation creates and returns a Connection object to the DriverManager. The DL/I implementation of JDBC is not fully JDBC compliant and the Driver member jdbcCompliant returns false.
| | | | | |
java.sql.Statement A Statement interface is returned from Connection.createStatement. The Statement and its subclass PreparedStatement define the interfaces that accept SQL statements and return tables as ResultSet objects. The code to create a statement is as follows:
| | | | | | | |
Statement statement = connection.createStatement();
Restriction: The DL/I implementation of Statement does not support: v Named cursors, therefore the method Statement.setCursorName throws an SQLException. v Aborting a DL/I operation, therefore Statement.cancel throws an SQLException. v Setting a time-out for DL/I operations, therefore Statement.setQueryTimeout and Statement.getQueryTimeout throw an SQLException.
Chapter 3. Accessing an IMS Database
31
JDBC Access Method | | | | | | |
java.sql.ResultSet The ResultSet interface defines an iteration mechanism to retrieve the data in rows of a table, and to convert the data from the type defined in the database to the type required in the application. For example, ResultSet.getString converts an integer or decimal data type to an instance of a Java String. The code to return ResultSet is as follows:
| | |
Rather than building a complete set of results after a query is run, the DL/I implementation of ResultSet retrieves a new segment occurrence each time ResultSet.next is called.
| | | | | | |
Restriction: The DL/I implementation of ResultSet does not support: v Returning data as an ASCII stream, therefore ResultSet.getAsciiStream throws an SQLException. v Named cursors, therefore ResultSet.getCursorName throws an SQLException. v The method ResultSet.getUnicodeStream, which is deprecated in JDBC 2.0.
| | | |
java.sql.ResultSetMetaData This interface defines methods to provide information about the types and properties in a ResultSet object. It includes methods such as getColumnCount, isSigned, getPrecision, and getColumnName.
| | | | |
java.sql.PreparedStatement The PreparedStatement interface extends the Statement interface, adding support for pre-compiling an SQL statement (the SQL statement is provided at construction instead of execution) and for substituting values in the SQL statement (UPDATE Suppliers SET Status = ? WHERE City = ?).
|
ResultSet results = statement.executeQuery(queryString);
Supported Data Types in IMS Java
| |
IMS Java supports the following JDBC types. The DLIModel Summary Report indicates the JDBC type that was assigned to each field in your database view.
|
Table 1. Supported Data Types
|
JDBC Type
Java Type
|
CHAR
String
|
VARCHAR
String
|
BIT
boolean
|
TINYINT
byte
|
SMALLINT
short
|
INTEGER
int
|
BIGINT
long
|
FLOAT
float
|
DOUBLE
double
|
BINARY
byte[]
|
PACKEDDECIMAL
java.math.BigDecimal
|
ZONEDECIMAL
java.math.BigDecimal
|
DATE
java.sql.Date
|
TIME
java.sql.Time
32
IMS Java User’s Guide
JDBC Access Method |
Table 1. Supported Data Types (continued)
|
JDBC Type
Java Type
| |
TIMESTAMP
java.sql.Timestamp
| |
The following table shows the available get methods for accessing data of a certain JDBC type.
| | | | |
The methods that are marked with “X” are methods designed for accessing the given data type. No truncation or data loss occurs using those methods. The methods that are marked with “O” are all other legal calls; however, data integrity cannot be ensured using those methods. If the box is empty (it contains neither an “X” nor an “O”), using that method for that data type will result in an exception.
|
Table 2. ResultSet.getxxx Methods to Retrieve JDBC Types
|
BIGINT
FLOAT
DOUBLE
BIT
CHAR
VARCHAR
PACKEDDECIMAL
ZONEDECIMAL
X
O
O
O
O
O
O
O
O
O
O
|
getShort
O
X
O
O
O
O
O
O
O
O
O
|
getInt
O
O
X
O
O
O
O
O
O
O
O
|
getLong
O
O
O
X
O
O
O
O
O
O
O
|
getFloat
O
O
O
O
X
O
O
O
O
O
O
|
getDouble
O
O
O
O
O
X
O
O
O
O
O
|
getBoolean
O
O
O
O
O
O
X
O
O
O
O
|
getString
O
O
O
O
O
O
O
X
X
O
O
|
getBigDecimal
O
O
O
O
O
O
O
O
O
X
X
|
getBytes
|
getDate
O
O
|
getTime
O
O
| |
getTimestamp
O
O
| |
Note: PACKEDDECIMAL and ZONEDDECIMAL are IMS Java JDBC types. All others are standard SQL types defined in SQL92.
| | |
Restriction: PackedDecimal and ZoneDecimal data types do not support the Sign Leading or Sign Separate modes. Sign information is always stored with the Sign Trailing method.
| | | |
TIMESTAMP
INTEGER
getByte
TIME
SMALLINT
|
DATE
ResultSet.getxxx Methods
BINARY
| |
TINYINT
JDBC Types
O
O
O
O
X X
O
O X
O
O
X
General Mappings from COBOL Copybook Types to IMS Java and Java Data Types Table 3 on page 34 describes how COBOL copybook types are mapped to DLITypeInfo constants and Java data types.
Chapter 3. Accessing an IMS Database
33
JDBC Access Method |
Table 3. Mapping from COBOL to IMS and Java
|
CopyBook Format
DLITypeInfo Constant
Java Type
|
PIC X
CHAR
java.lang.String
1
2
|
PIC 9 BINARY
(see Table 4)
(see Table 4)2
|
COMP-1
FLOAT
float
|
COMP-2
DOUBLE
double
PACKEDDECIMAL
java.math.BigDecimal
ZONEDDECIMAL
java.math.BigDecimal
3
|
PIC 9 COMP-3
4
| |
PIC 9 DISPLAY
| | | | | | | |
Notes: 1. Synonyms for BINARY data items are COMP and COMP-4. 2. For BINARY data items, the DLITypeInfo constant and Java type depend on the number of digits in the PICTURE clause. Table 4 describes the type based on PICTURE clause length. 3. PACKED-DECIMAL is a synonym for COMP-3. 4. If the USAGE clause is not specified at either the group or elementary level, it is assumed to be specified as DISPLAY.
|
Table 4. DLITypeInfo Constants and Java Types based on PICTURE clause
| |
Digits in PICTURE clause
Storage Occupied
DLITypeInfo Constant
Java Type
|
1 through 4
2 bytes
SMALLINT
short
|
5 through 9
4 bytes
INTEGER
int
| |
10 through 18
8 bytes
BIGINT
long
| |
Table 5 shows examples of specific CopyBook formats mapped to DLITypeInfo constants.
|
Table 5. CopyBook Formats Mapped to IMS Java Types
|
CopyBook Format
DLITypeInfo Constant
|
PIC X(25)
CHAR
|
PIC S9(04) COMP
SMALLINT
|
PIC S9(06) COMP-4
INTEGER
|
PIC S9(12) BINARY
BIGINT
|
COMP-1
FLOAT
|
COMP-2
DOUBLE
|
PIC S9(06)V99
ZONEDDECIMAL
|
PIC 9(06).99
ZONEDDECIMAL
| |
PIC S9(06)V99 COMP-3
PACKEDDECIMAL
| |
Supported SQL Grammar The following SQL keywords are currently supported in IMS Java. All keywords are case insensitive. SELECT FROM WHERE
| | | | |
34
IMS Java User’s Guide
SQL Grammar INSERT DELETE UPDATE ALL AND DISINCT INTO OR
| | | | | | | |
Restriction: IMS Java does not support aggregate keywords .
| |
SELECT
| | | | |
A SELECT statement is a query used as a top-level SQL statement. A SELECT statement can be executed against a Statement or PreparedStatement object that returns the results as a ResultSet object. Figure 12 on page 36 shows sample code that uses the results of a SELECT query to update modelOutput with the model information. This example requires an inputMessage with the ModelTypeCode.
| |
Notice that the PCB reference name, DealershipDB, qualifies the Model segment name in the query string.
| | | | | | | | | | |
Segment-Qualifying Fields SQL dictates that whenever a field is common between two tables in an SQL query, the desired field must be table qualified to resolve the ambiguity. Similarly, whenever a field name is common in any two segments along a hierarchical path, the field must be segment qualified. For example, if a PCB has two segments, segment ROOT and segment CHILD, and both possess a field named id, any query referencing the id field must be segment qualified. The following example is incorrect because the id field is not segment qualified: SELECT id FROM PCBName.CHILD WHERE id=’10’
| | | |
The following example is correct because the id field is segment qualified:
| | | | | | | |
Recommendations: v For performance reasons, always segment qualify fields (unless readability is seriously sacrificed). A performance improvement is realized since IMS Java does not need to search through all the segments to locate the field and check for ambiguity. v It is not necessary to provide the PCB reference name on the query unless the query is ambiguous without it; however, it is recommended that you always provide it to remove ambiguity and to remove the need for checking.
SELECT CHILD.id FROM PCBName.CHILD WHERE ROOT.id=’10’
|
Chapter 3. Accessing an IMS Database
35
SQL Grammar public boolean getModelDetails(InputMessage inputMessage, ModelOutput modelOutput) throws IMSException {
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
// Parse the input message for ModelTypeCode String queryString = "SELECT * from DealershipDB.Model where ModelTypeCode = " + "’" + inputMessage.getString("ModelTypeCode").trim() + "’"; // Create a statement and execute it to get a ResultSet try { Statement statement = connection.createStatement(); ResultSet results = statement.executeQuery(queryString); // Send back the result of the query // Note: since "ModelTypeCode" is unique - only 1 row // is returned if (results.next()) { modelOutput.setString("ModelTypeCode", results.getString("Type").trim()); modelOutput.setString("Make", results.getString("CarMake").trim()); modelOutput.setString("Model", results.getString("CarModel").trim()); modelOutput.setString("Year", results.getString("CarYear")); modelOutput.setString("CityMiles", results.getString("EPACityMileage").trim()); modelOutput.setString("HighwayMiles",results.getString ("EPAHighwayMileage").trim()); modelOutput.setString("Price", results.getString("Price").trim()); modelOutput.setString("Horsepower", results.getString("Horsepower").trim()); return true; } else { reply("Unknown Type"); return false; } } catch (SQLException e) { reply("Query Failed:"+ e.toString()); return false; }
}
| | | | | |
Figure 12. Example of SELECT Query Results
Note: Note the use of trim() in Figure 12. The method trim() is used because IMS character fields are padded with blanks if they are not long enough. It trims off the extra blanks in the return.
| | | | |
Figure 12 illustrates the use of a Statement object for executing an SQL query. You can also use a PreparedStatement object to execute an SQL query. A PreparedStatement object has two advantages over a Statement object: v The SQL can be parsed one time for many executions of the query v You can build the query and use substitute values with each execution
| | | | | | |
The following two queries are equivalent: SELECT CarModel FROM DealerDB.Model WHERE CarYear=’1989’ SELECT Model.CarModel FROM DealerDB.Model WHERE Model.CarYear=’1989’
36
IMS Java User’s Guide
SQL Grammar In IMS Java, you specify only the segment furthest down the hierarchy in the FROM clause. You can query different segments by preceding the field name with the segment name, as in:
| | | | | | | |
SELECT Dealer.DealerName,CarModel FROM DealershipDB.Model WHERE CarMake=’Ford’
FROM A FROM clause in IMS Java differs from standard SQL in that no explicit joins are required nor allowed. Rather, the deepest segment to be accessed should be listed in the FROM clause. This then implies a join of all the segments starting with the one listed in the FROM clause up the hierarchy to the root. For more information see “JDBC Access Method” on page 24.
| | | | | |
WHERE
| | | | |
By using IMS Java to write IMS applications, you can avoid the long process of coding segment search arguments (SSAs) for every segment in the path leading to the segment being queried. Instead, you can use the IMS Java API for SQL queries to retrieve results from any segment in the path leading to the segment being queried.
| | |
The primary difference between SQL queries to relational databases and JDBC queries to IMS using IMS Java is that the hierarchical structure of an IMS database eliminates the need for the join required for tables in relational databases.
| | | | | | |
For example, Figure 13 is a query to a relational database for the address of a dealership that sells a particular car model that you are looking for (AnyCarModel): SELECT Dealer.Address FROM Dealer.Model WHERE Model.CarMake = ’AnyCarModel’ AND Dealer.DealerName = Model.CarrierName
| |
Figure 13. Sample Query
| |
You must query two independent tables (Dealer and Model) and indicate how they are joined in the WHERE clause.
| | | | | |
In an IMS Java application, you can write the query in Figure 14 to access the same data in a hierarchical database in a WHERE clause: SELECT Dealer.Address FROM DealershipDB.Model WHERE Model.CarMake = ’AnyCarModel’
| |
Figure 14. Sample Query
| | | | |
In a hierarchical database, all data in segments along the hierarchical path to the target segment are implicitly included in the query results and therefore do not need to be explicitly stated. In Figure 14, the information about the Dealer segment is included in the result set, because it is along the hierarchical path to the Model segment.
Chapter 3. Accessing an IMS Database
37
SQL Grammar | | | | |
However, in the case of the asterisk operator (*) in a SELECT query, a path call is not made. In the sample query below, only the fields from the Model segment are retrieved.
| |
If fields from more than one segment are desired, they must all be explicitly requested in the SELECT clause.
| | | | | | | |
You can use the following operators between field names and values in individual predicates: < <= = =< < !=
| |
You can combine multiple predicates with AND and OR operators. However, you cannot use parentheses and AND always takes precedence over OR.
|
SELECT * FROM DealershipDB.Model
INSERT
| | | | | |
An INSERT statement inserts a segment instance with the specified data under any number of parent segments matching the criteria specified in the WHERE clause. All column names must be in the statement, except when the value of a field is specifically set in the database view. For more information see “Adding Default Values for Fields of a Segment” on page 99. Figure 15 shows an example of an INSERT statement that inserts a field in the database:
| | | | | | | | |
String insertString = "INSERT INTO DealershipDB.Sales " + "(DateSold, PurchaserLastName, PurchaserFirstName, " + "PurchaserAddress, SoldBy, StockVINumber)" + " VALUES (’07032000’, ’Beier’, ’Otto’, " + "’101 W. 1st Street, Springfield, OH’, " + "’S123’, ’1ABCD23E4F5678901234’) " + "WHERE Dealer.DealerNumber = ’A123’" + "’ AND ModelTypeCode = ’K1’)";
| | | | |
Figure 15. Sample INSERT Statement
It is possible to set default values for any field in a segment. For more information see “Adding Default Values for Fields of a Segment” on page 99. A difference between JDBC queries to relational databases and IMS is that standard SQL does not have a WHERE clause in an INSERT statement, as tuples are just being inserted into the table specified after the INTO keyword. In an IMS DL/I database, you are actually inserting a new instance of the specified segment, so you need to know where in the database this segment occurrence needs to be placed. In the case of an INSERT statement, the WHERE clause is necessary in all cases except when inserting a root segment. In the case of a prepared statement, the list of values can have a ? as the value that can be substituted before the statement is executed. For example:
| | | | | | | | |
38
IMS Java User’s Guide
SQL Grammar INSERT INTO DealerDB.Model(ModelTypeCode, CarMake, CarModel, CarYear, Price, EPACityMileage, EPAHighwayMileage, Horsepower) VALUES (?,?,?,?,?,?,?,?) WHERE Dealer.DealerNumber=?
| | | | | |
DELETE
| | | | |
A DELETE statement can delete any number of segment occurrences matching the criteria specified in the WHERE clause. A DELETE statement with a WHERE clause also deletes the child segments of the matching segments. If no WHERE clause is specified, all of the segment occurrences of that type are deleted as are all of its child segment occurrences. Figure 16 shows an example of a DELETE statement:
| | | | | | | | | | | | |
String updateString = "DELETE from DealershipDB.Order WHERE " + "Dealer.DealerNumber = ’" + dealerDesired+ "’ AND " + "OrderNumber = ’" + orderDesired + "’"; try { Statement statement = connection.createStatement(); int results = statement.executeUpdate(updateString); ... } catch (SQLException e) { ... }
| | | |
Figure 16. Sample DELETE Statement
UPDATE
|
An UPDATE statement modifies the value of any number of segment occurrences.
| | | |
An UPDATE statement applies its SET operation to each instance of a specified segment with matching criteria in the WHERE clause. If the UPDATE statement does not have a WHERE clause, the SET operation is applied to all instances of the specified segment.
| | | | | | | | | | | | | | |
A SET clause contains at least one assignment. In each assignment, the values to the right of the equal sign are computed and assigned to columns to the left of the equal sign. For example, the UPDATE statement in Figure 17 is called to accept an order. When a customer accepts an order, the car’s “SerialNo” and delivery dates are filled in:
| | |
String updateString = "UPDATE DealershipDB.Order " + "SET SerialNo = ’" + inputMessage.getString("StockVINumber").trim() + "’, " + "DeliverDate = ’" + inputMessage.getString("Date").trim() + "’ WHERE OrderNumber = ’" + inputMessage.getString("OrderNumber").trim() + "’";
Figure 17. Sample UPDATE Statement
Chapter 3. Accessing an IMS Database
39
SQL Grammar |
JDBC Prepared Statements for SQL
| | | |
To improve performance of your IMS Java application, use JDBC prepared statements for the SQL. The PreparedStatement completes the initial steps in preparing queries only once so that you only need to provide the parameters before each repeated database call.
| | | |
The PreparedStatement performs the following only once before repeated database calls are made: 1. Parses the SQL 2. Cross-references the SQL with the IMS Java DLIDatabaseView 3. Builds SQL into SSAs before a database call is made
| |
Recommendations for JDBC
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Although the JDBC interface to an IMS database follows the relational paradigm closely, remember that the segments are physically stored in a hierarchical database, which affects the semantics of your JDBC calls to some extent. To avoid unexpected results, or potential performance problems, consider the following: v When performing a SELECT, generally try to supply predicates in the WHERE clause for all levels down the hierarchy to your target segment. – If you supply a predicate in the WHERE clause for some target segment somewhere down the hierarchy, and omit predicates for its parents, then IMS will scan all candidate segments at the parent levels in an attempt to match the predicate you have supplied. For example, if you are retrieving a second level segment and you supply a a predicate for that second level segment, but do not supply one for the root segment, then IMS may perform a full database scan, testing every second-level segment under every root against the predicate. This has performance implications, particularly at the root level, and may result in unexpected segments being retrieved.
| | |
Note: When considering the effects of the database hierarchy on your JDBC operations, you can find a description of the hierarchy, as it appears in your application view, in the DLIModel Java Report.
– A similar consideration applies to locating segments for UPDATEs. v When inserting a new segment, generally try to supply predicates in the WHERE clause for all levels down the hierarchy to your target new segment. If you omit a predicate for any level down to the insert target segment, then IMS will choose the first occurrence of a segment at that level that allows it to satisfy remaining predicates, and perform the insert in that path. This may not be what you intended. To take an example of a three-level database, if you insert a third-level segment, supply a predicate for the root, but none at the second-level, your new segment will always be inserted under the first second-level segment under the specified root. v When deleting a segment that is not a bottom-level segment in its hierarchy (in other words, a leaf segment), be aware that you have, in effect, cascaded deletes down the remaining segments in that hierarchical subtree. The entire family of segments of all types that are located hierarchically below your target deleted segment will also (generally) be deleted. v Although not solely related to hierarchies, note that when providing predicates to identify a segment, the search is generally faster if the predicate is qualified on a primary or secondary index key field, rather than simply a ″search field″. Primary and secondary key fields are identified for each segment in the DLIModel Java Report.
40
IMS Java User’s Guide
IMS Java Hierarchic Database Interface | |
IMS Java Hierarchic Database Interface
| | | | |
Even though you can use the lower-level package to access IMS data, it is recommended that you use the JDBC package. This package is included for experienced IMS application developers who need more access than the higher-level package provides. The IMS Java Hierarchic Database Interface contains the following objects and classes:
| | | |
DLIConnection A DLIConnection object represents a connection with a set of DL/I databases or views (as many PCBs as are in the PSB). It provides the interface to read, update, insert, and delete segments in a DL/I database.
| | | |
DLISegment DLISegment is the class that represents segments in a DL/I database. It registers the types of data stored in a segment by providing an array of DLITypeInfo objects. Definition: Setter and getter functions use the type information to automatically locate and convert data in the byte array to the requested format. These setter and getter functions can locate data based on both its offset in the DLITypeInfo array (fastest) or by using the name of the field included in the type information.
| | | | | | | | |
DLITypeInfo DLITypeInfo, contained in the base package, defines the type, offset, and length of a field in the byte array of a DLISegment. DLITypeInfo supports all DB2 for OS/390 data types, including packed decimal.
| |
SSA
| | | | | |
SSAList SSAList represents a collection of SSA objects and converts the list to the byte array necessary to invoke the JavaToDLI methods. The combination of SSAList, SSA, and SSAQualification statement allows an application to specify a Segment Search Argument list that fully supports all of its features.
| | | |
SSAQualificationStatement An SSAQualificationStatement represents logical qualification statements to a Segment Search Argument. Qualification statements support both key search fields and search fields.
| | | | |
DLIRecord DLIRecord represents the set of segment occurrences from a root segment down the hierarchy to the leaf segment. The DLIConnection methods getUniqueRecord and getNextRecord update a DLIRecord object using a path call (“D” command code).
| | |
DLISegmentInfo DLISegmentInfo is a “wrapper” class that links a DLISegment object to its parent in the DL/I database hierarchy.
| | | | |
DLIDatabaseView DLIDatabaseView represents an application’s view of the segments in a DL/I database. It is built as an array of DLISegmentInfo objects, which bind a DLISegment object to its parent DLISegment object. DLIDatabaseView therefore defines the segment hierarchy. DLIDatabaseView also provides
SSA represents a Segment Search Argument. It provides methods to add command codes and qualification statements.
Chapter 3. Accessing an IMS Database
41
IMS Java Hierarchic Database Interface named lookup of the DLISegment objects. This feature is used by the DL/I JDBC implementation to locate a DLISegment object from the name of a segment used in a query.
| | | |
Application Programming Using DLIConnection
| | | | | | | | | |
To use DLIConnection to read, update, insert, and delete segment instances, your application should: 1. Acquire DLISegment object for each segment using the cloneSegment method on the subclassed DLIDatabaseView 2. Provide a subclass of DLIDatabaseView that defines the segment hierarchy accessed by the application
| | | |
You may create the required classes by coding them manually (see Appendix A, “Manually Creating IMS Java Metadata Classes” on page 99), or by running the DLIModel utility (See Chapter 5, “DLIModel Utility” on page 61). It is recommended that you use the DLIModel utility wherever possible.
|
3. Create a DLIConnection object to access the database 4. Create an SSAList object 5. Invoke the database access methods of DLIConnection to read, write, or delete segments from the database
Creating a DLIConnection Object
| |
A DLIConnection object must be created in one of two ways: v By providing a DLIDatabaseView object v By providing the fully qualified name of the DLIDatabaseView
| | |
When coding directly to DLIConnection, it is faster to create and pass the DLIDatabaseView object, because it simplifies finding the class by its name. Figure 18 illustrates how to create a DLIConnection object:
| | |
DealerDatabaseView dealerView = new DealerDatabaseView(); DLIConnection connection = DLIConnection.createInstance(dealerView);
|
| | | |
Figure 18. Creating a DLIConnection Object
Building SSAs
| | | | | |
SSAs are used to identify the segment to which a DL/I call applies. Due to the hierarchical structure DL/I uses, you often have to specify several levels of SSAs to access a segment at a low level in the hierarchy. An SSAList is a collection of one or more SSAs and the SSAList is what is used in making any DL/I call. The SSAList is also where you specify which database you want to access within a DLIDatabaseView by providing the PCB reference name.
| |
Figure 19 on page 43 illustrates how to create an SSAList that will find all “Alpha” cars made in 1989:
|
42
IMS Java User’s Guide
IMS Java Hierarchic Database Interface | | | | | | | | | | | | | | | | | | | | | | |
// Create an SSAList SSAList modelSSAList = SSAList.createInstance("DealershipDB"); // Construct an unqualified SSA for the Dealer segment SSA dealerSSA = SSA.createInstance("Dealer"); // Construct a qualified SSA for the Model segment SSA modelSSA = SSA.createInstance("Model", "CarMake", SSA.EQUALS, "Alpha"); // Add an additional qualification statement modelSSA.addQualification(SSA.AND, "CarYear", SSA.EQUALS, "1989"); // Add the SSAs to the SSAList modelSSAList.addSSA(dealerSSA); modelSSAList.addSSA(modelSSA);
Figure 19. Creating an SSAList
Accessing DL/I Data using SSAs You can now issue a database call by invoking the desired access method on DLIConnection passing in: v the SSAList v an instance of the segment, that will be the intended target of the database call results
| | |
This passed-in instance should be obtained by calling the cloneSegment method on the DLIDatabaseView. Finally, the passed-in segment can be examined for the results of the query.
| | | | | | | |
The following example demonstrates calling and printing-out the results using the SSAList built in the preceding section: DLISegment model = dealerView.cloneSegment("Model"); boolean recordRead = connection.getUniqueSegment(model, modelSSAList); while (recordRead) { System.out.println("Car Name: " + model.getString("ModelName")); recordRead = connection.getNextSegment(model, modelSSAList); }
|
Chapter 3. Accessing an IMS Database
43
IMS Java Hierarchic Database Interface
44
IMS Java User’s Guide
| |
Chapter 4. Writing a Java Application Program
| | |
This chapter uses the sample applications shipped with IMS Java to show how to write IMS Java applications in different environments. For information on expanding and locating these files, see the Readme file in the samples directory.
| | | | |
All samples use a car dealership example and use JDBC for database processing. All samples process a common set of databases, and the jobs to define and load these databases are contained in the directory samples/dealership/databases. For information on how to run the database definition and load jobs, see the IMS sample Readme file in the directory samples/dealership/ims/Readme. In this Chapter: v “IMS Applications” v “CICS Applications” on page 59 v “DB2 Stored Procedures” on page 59
IMS Applications Overview of IMS Application Processing Using the IMS Java classes, you can write applications for the following types of IMS dependent regions: | | | | | | | |
Java message processing (JMP) regions JMP regions are similar to MPP regions, but JMP regions only allow the scheduling of Java message-processing programs. A JMP is started when there is a message in the queue for the JMP and IMS schedules the message to be processed. JMP programs are executed through transaction codes submitted by users at terminals and from other application programs. Each transaction code represents a transaction that the JMP processes. A single program can also be started from multiple transaction codes.
| | | | | | | |
JMP programs are very flexible in how they process transactions and where they send the output. JMP programs send any output messages back to the message queues and processes the next message with the same transaction code. The program continues to run until there are no more messages with the same transaction code. JMPs share the following characteristics: v They are small v They can produce output that is needed immediately
| | | | | | |
Java batch processing (JBP) regions JBP regions run flexible programs that perform batch-type processing online and can access the IMS message queues for output (similar to non-message–driven BMPs). JBPs are started by submitting a batch job with, for example, JCL or a TSO session. JBPs are like BMPs, except that they cannot read input messages from the IMS message queue (for example: there is no IN= parameter in the startup procedure).
| |
IMS Java applications can run in a DB/DC and DBCTL environments. IMS Java does not support batch processing.
© Copyright IBM Corp. 2000, 2002
45
IMS Applications
Running Java Applications After determining the appropriate type of Java program to use, you must give your program specific instructions from the terminal to run it. You can access programs from terminals by providing one of the following types of input: IMS Commands Start with slash (/). For example: /START.
| |
Related Reading: See IMS Version 7 Command Reference for more information on IMS commands. Transaction message A transaction message is routed to an application program for processing. The program destination is defined by the 1- to 8-byte transaction code included as the first part of the input message. Message switch A message switch is routed to another terminal. The terminal destination is defined by the 1- to 8-byte terminal name included as the first part of the input.
Message Queuing After you provide input in one of the forms described above, the message is either queued or sent directly to command process or modules. Specifically, all full-function database input and output messages are placed in message queues, waiting to be enqueued to their destinations or points of completion. However, before getting to the points of completion, IMS message queues are held in buffers in main storage until they are either directed to their destination or there is a backlog of messages arriving in the queue. If there are more messages entering the queue than exiting, IMS writes messages to the message queue data sets until they are directed to their final destinations. Related Reading: See the IMS Primer for general information on IMS message queues.
Reading and Writing Messages to the Message Queue in Java A basic IMS Java application involves the input and receipt of multiple messages from the message queue, much like applications in other languages. IMS Java applications are invoked by transactions; that is, a user at a terminal can communicate with the application program and IMS. The actual applications are built with the application package classes using the IMS Java classes and methods.
Building an IMS Java Application by Example | | | | | |
In “Introduction to the Example Environment” on page 23, a sample application program is introduced. The sample program uses an automobile dealership program for illustration purposes. This and other automobile dealership applications are available in the samples.tar file shipped with the IMS Java product (See the Readme file in the samples directory for instructions on how to expand and access these sample applications).
| | |
Related Reading: For a full specification of the classes used in this chapter, see the JavaDoc shipped with IMS Java. If using the default installation directory, the JavaDoc is in directory usr/lpp/ims/imsjava71/docs/.
Using IMS Java to Build a Message Processing Application To build an IMS Java message processing application, follow these steps: 1. Subclass IMSApplication.
|
46
IMS Java User’s Guide
IMS Applications
|
The entry point into the business application is via the doBegin method of the subclass, which is described in “Subclass IMSApplication and Implement main() and doBegin()” on page 48. The doBegin method is an abstract method in the base class, IMSApplication. Important: The main method of your subclass must call the begin method of the base class, IMSApplication. The begin method of the base class then performs initialization and calls the abstract doBegin method that was implemented in your subclass. 2. Receive and send IMSFieldMessages.
| | |
3. Perform a commit before processing the next message by calling IMSTransaction.getTransaction().commit() by calling IMSTransaction.getTransaction().abend().
| | | |
Subclass IMSFieldMessage to Define Any Input Messages: Figure 20 gives an example of subclassing IMSFieldMessage to define an input message that accepts a two-byte type code of a car model to query a car dealership database for available car models.
| | | | | | | | |
This example code subclasses IMSFieldMessage to make the fields in the message available to the program and creates an array of DLITypeInfo objects for the fields in the message. For the DLITypeInfo, the code identifies first the field name, then the data type, the position, and finally the length of the individual fields within the array. This allows the application to use the access functions within IMSFieldMessage to automatically convert the data from its format in the message to a Java type that the application can process. In addition to the message-specific fields it defines, IMSFieldMessage provides access functions that allow it to determine the transaction code and the length of the message.
| | | | | | | | | | | | | | | | |
package dealership.application; import com.ibm.ims.db.*; import com.ibm.ims.base.*; import com.ibm.ims.application.*; /* Subclasses IMSFieldMessage to define application’s input messages */ public class InputMessage extends IMSFieldMessage { /* Creates array of DLITypeInfo objects for the fields in message */ final static DLITypeInfo[]fieldInfo={ new DLITypeInfo("ModelTypeCode", DLITypeInfo.CHAR, 1, 2) };
}
public InputMessage() { super(fieldInfo, 2, false); }
Figure 20. Subclass IMSFieldMessage: Input Message Sample Code
| | |
Subclass IMSFieldMessage to Define any Output Messages: Figure 21 on page 48 gives an example of subclassing IMSFieldMessage to define an output message that displays the available car models from a type code query.
| | | | |
This example code creates an array of DLITypeInfo objects and then passes that array, the byte array length, and the boolean value false (indicates a non-SPA message) to the IMSFieldMessage constructor. For each DLITypeInfo object, you must first identify the field data type, then the field name, the field offset in the byte array, and finally the length of the byte array. Chapter 4. Writing a Java Application Program
47
IMS Applications package dealership.application; import com.ibm.ims.db.*; import com.ibm.ims.base.*; import com.ibm.ims.application.*;
| | | | | | | | | | | | | | | | | | | | | | | |
/*Subclasses IMSFieldMessage to define application’s output messages */ public class ModelOutput extends IMSFieldMessage { /* Creates array of DLITypeInfo objects for the fields in message */ final static DLITypeInfo[] fieldInfo={ new DLITypeInfo("Type", DLITypeInfo.CHAR, 1, 2), new DLITypeInfo("Make", DLITypeInfo.CHAR, 3, 10), new DLITypeInfo("Model", DLITypeInfo.CHAR, 13, 10), new DLITypeInfo("Year", DLITypeInfo.DOUBLE, 23, 4), new DLITypeInfo("CityMiles", DLITypeInfo.CHAR, 27, 4), new DLITypeInfo("HighwayMiles", DLITypeInfo.CHAR, 31, 4), new DLITypeInfo("Horsepower", DLITypeInfo.CHAR, 35, 4) }; public ModelOutput() { super(fieldInfo, 38,false); } }
|
Figure 21. Subclass IMSFieldMessage: Output Message Sample Code
| | | | |
Subclass IMSApplication and Implement main() and doBegin(): The example code shown in Figure 22 on page 49 demonstrates how to perform the following actions: 1. Subclassing IMSApplication. 2. Instantiating the subclass in the main method.
| | | | | | | | |
3. Calling the IMSApplication.begin() method. 4. Implementing the application in the doBegin() method of the subclass. (See “Programming Models for IMS Java Applications” on page 49 for more information on the normal flow of this method) 5. Querying the database for a specific model that matches the input model type code. This method is not implemented yet and is explained more fully in Chapter 3, “Accessing an IMS Database” on page 23. 6. Returning detailed information as output about that specific model if it is available at the dealership. 7. Returning an error message if the model is not available at the dealership.
|
48
IMS Java User’s Guide
IMS Applications | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
package dealership.ims; import com.ibm.ims.application.*; public class IMSAuto extends IMSApplication {1 IMSMessageQueue messageQueue = null; InputMessage inputMessage = null; ModelOutput modelOutput = null; public IMSAuto() { super(); } public static void main(String args[]) { IMSAuto imsauto = new IMSAuto(); 2 imsauto.begin(); 3 } public void doBegin() throws IMSException { 4 messageQueue = new IMSMessageQueue(); inputMessage = new InputMessage(); modelOutput = new ModelOutput(); while(messageQueue.getUniqueMessage(inputMessage)) { if (!inputMessage.getString ("ModelTypeCode").trim().equals("")){ if (getModelDetails(inputMessage, modelOutput))5 messageQueue.insertMessage(modelOutput); 6 } else { reply("Invalid Input"); 7 } IMSTransaction.getTransaction().commit(); }
}
public void reply(String errmsg) throws IMSException{ ErrorMessage errorMessage = new ErrorMessage(); errorMessage.setString("MessageText",errmsg); messageQueue.insertMessage(errorMessage);
} }
Figure 22. Subclass IMSApplication Sample Code
| | | | | | | | | | |
Note: IMSMessageQueue.getUniqueMessage returns true if a message was read from the queue and false if one was not. Also, IMSTransaction.getTransaction().commit must be called before receiving subsequent messages from the queue.
Programming Models for IMS Java Applications The following programming models outline the supported structure for IMS applications that run in JMP regions or JBP regions. The models are not complete, but show the normal flow of the doBegin method (See 4 in the previous section) for both the JDBC and SSA access methods. These models use JDBC, but for the SSA database access method, database access happens in the same places in the program flow as with JDBC.
Chapter 4. Writing a Java Application Program
49
IMS Applications | | |
JMP Programming Models
| | |
JMP programs are started when IMS receives a message with a transaction code for the JMP program and schedules the message. JMP programs end when there are no more messages with that transaction code to process.
| | | | | | | | | | | | | | | | | | | | | | | | |
JMP Program Without Rollback: Every time the program runs, the program connects to an IMS database and disconnects when it has processed all of the messages. A transaction begins when the program gets an input message and ends when the program commits the transaction. Database processing is done only after the getUniqueMessage call and before the commit call. The program cannot perform database processing after the commit call and either before the next getUniqueMessage call or the return.
| | | | | | | | | | | | | | | | | | | | | | | | | | | |
JMP Program using Rollback: A JMP program can roll back database processing and output messages any number of times during a transaction. A rollback call backs out all database processing and output messages to the most recent commit. The transaction must still end with a commit call when the program issues a rollback call, even if there is no further database processing or messages after the rollback.
JMP programs get input messages from the IMS message queue, access IMS databases, commit transactions, and can send output messages.
public void doBegin() ... {
//Application logic runs
conn = DriverManager.getConnection(...); //Establish DB connection repeat { MessageQueue.getUniqueMessage(...);
}
}
//Get input message, which
results=statement.executeQuery(...); //Perform DB processing ... MessageQueue.insertMessage(...); //Send output messages ... IMSTransaction.commit(); //Commit and end transaction
conn.close(); return;
public void doBegin() ... {
//Close DB connection
//Application logic runs
conn = DriverManager.getConnection(...); //Establish DB connection repeat { MessageQueue.getUniqueMessage(...);
//Get input message, which
results=statement.executeQuery(...); //Perform DB processing ... MessageQueue.insertMessage(...); //Send output messages ... IMSTransaction.rollback(); //Back out of DB processing and //output messages results=statement.executeQuery(...); //Perform more DB processing //(optional) ... MessageQueue.insertMessage(...); //Send more output messages //(optional) ... IMSTransaction.commit(); //Commit and end transaction
50
IMS Java User’s Guide
IMS Applications | | | | |
}
}
conn.close(); return;
//Close DB connection
| | | | | | | | | | | | | | | | | | | | | | | | | | | | |
JMP Program With Per-Transaction Connections: A JMP program needs to open a database connection only once to process multiple transactions. However, a JMP program can open and close a database connection for each transaction processed. The disadvantage is that you add some code complexity and lose a small amount of performance. But an advantage is it might be easier to port the application to other environments where per-transaction connections are required. These per-transaction connections are required if the program uses DB2 interoperability to issue any DB2 database calls.
| | | |
JBP Programming Models
| | | | | | | | | | | | | | | | | | |
JBP Program Without Rollback: A JBP program connects to a database, performs database processing, sends any output messages, periodically commits, and disconnects from the database at the end of the program. The program must issue a final commit before ending.
public void doBegin() ... {
//Application logic runs
conn = DriverManager.getConnection(...);
//Establish DB connection
repeat { conn = DriverManager.getConnection(...); //Establish DB connection
} }
MessageQueue.getUniqueMessage(...);
//Get input message, which
results=statement.executeQuery(...); ... MessageQueue.insertMessage(...); ... conn.close();
//Perform DB processing
IMSTransaction.commit();
//Commit & end transaction
//Send output messages //Close DB connection
return;
JBP application programs are similar to JMP programs, except that JBP programs do not receive input messages from the message queue. The program should periodically issue commit calls, except for PROCOPT=GO programs.
public void doBegin() ... {
//Application logic runs
conn = DriverManager.getConnection(...);
//Establish DB connection
repeat { repeat { results=statement.executeQuery(...); //Perform DB processing ... MessageQueue.insertMessage(...); //Send output messages ... } }
IMSTransaction.commit();
//Periodic commits divide work
Chapter 4. Writing a Java Application Program
51
IMS Applications | | | |
}
conn.close(); return;
//Close DB connection
JBP Program using Rollback: Like JMP programs, JBP programs can also back out of database processing and output messages. A final commit call is required before the program can end, even if no database processing occurs or output messages are sent after the last rollback call.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
public void doBegin() ... { conn = DriverManager.getConnection(...);
//Application logic runs //Establish DB connection
repeat { repeat { results=statement.executeQuery(...); //Perform DB processing ... MessageQueue.insertMessage(...); //Send output messages ... IMSTransaction.rollback(); //Back out of DB //messages
} }
}
results=statement.executeQuery(...); //Perform more DB //processing (optional) ... MessageQueue.insertMessage(...); //Send more output //messages (optional) ...
IMSTransaction.commit();
conn.close(); return;
//Periodic commits divide work //Close DB connection
Additional Programming Considerations This section describes additional programming conderations: v “Conversational Transactions” v “Handling Multi-Segment Messages” on page 54 v “Coding and Accessing Messages with Repeating Structures” on page 55 v “Flexible Reading of Multiple Input Messages” on page 56
| | | | |
Conversational Transactions A conversational program runs in a JMP region and processes conversational transactions that are made up of several steps. It does not process the entire transaction at the same time. A conversational program divides processing into a connected series of terminal-to-program-to-terminal interactions. Use conversational processing when one transaction contains several parts.
| | | | |
A non-conversational program receives a message from a terminal, processes the request, and sends a message back to the terminal. A conversational program receives a message from a terminal and replies to the terminal, but it saves the data from the transaction in a scratch pad area (SPA). Then, when the person at the terminal enters more data, the program has the data it saved from the last message in the SPA, so it can continue processing the request without the person
52
IMS Java User’s Guide
IMS Applications | |
at the terminal having to enter the data again. The application package classes enable applications to be built using IMS Java.
| | |
Related Reading: For more information on conversational and nonconversational transaction processing, see IMS Version 7 Administration Guide: Transaction Manager.
| | | | | | | | |
Defining a SPA Message: Here are the steps to define a SPA message in a conversational program:
| | | | | | | |
1. Define the SPA message (including the boolean as a SPA parameter). By default, all messages going to (input) and from (output) an IMS Java application are transmitted as EBCDIC character data. To use a different type of encoding, you must call the IMSFieldMessage inherited member setDefaultEncoding and provide the new encoding. This encoding can be any Java supported encoding. In Figure 23, the default encoding is specified as UTF-8. public class SPAMessage extends IMSFieldMessage { static DLITypeInfo[] fieldInfo = { new DLITypeInfo("SessionNumber",DLITypeInfo.SMALLINT,1, 2), new DLITypeInfo("ProcessCode", DLITypeInfo.CHAR, 3, 8), new DLITypeInfo("LastName", DLITypeInfo.CHAR, 11,10), new DLITypeInfo("FirstName", DLITypeInfo.CHAR, 21,10), new DLITypeInfo("Extension", DLITypeInfo.CHAR, 31,10), new DLITypeInfo("ZipCode", DLITypeInfo.CHAR, 41, 7), new DLITypeInfo("Reserved", DLITypeInfo.CHAR, 48,19) }; public SPAMessage() { super(fieldInfo, 66, true); setDefaultEncoding("UTF-8"); } } Figure 23. Defining a SPA Message
2. Read the SPA message before reading the application messages: | | | | | | | | | | | | | | | | | | | | | |
try { // Get the SPA data msgReceived = msgQ.getUniqueMessage(spaMessage); } catch (IMSException e) { if (e.getStatusCode() != JavaToDLI.MESSAGE_QUEUED_PRIOR_TO_LAST_START) throw e; } if (!msgReceived) outputMessage.setString("Message","UNABLE TO READ SPA"); else if (!msgQ.getNextMessage(inputMessage)) // No input message received outputMessage.setString("Message","NO INPUT MESSAGE"); else if ((spaMessage.getShort("SessionNumber")==0) && (!inputMessage.getString("ProcessCode").trim().equals("END")) && (inputMessage.getString("LastName").trim().equals(""))) // New Conversation. User has to specify last name. outputMessage.setString("Message","LAST NAME WAS NOT SPECIFIED"); else { }
| | |
Figure 24. Reading the SPA Message
Chapter 4. Writing a Java Application Program
53
IMS Applications 3. Write the SPA message before sending any output messages: // Set spa data fields spaMessage.setString("ProcessCode", inputMessage.getString("ProcessCode")); spaMessage.setString("LastName", inputMessage.getString("LastName")); spaMessage.setString("FirstName", inputMessage.getString("FirstName")); spaMessage.setString("Extension", inputMessage.getString("Extension")); spaMessage.setString("ZipCode", inputMessage.getString("ZipCode")); spaMessage.incrementSessionNumber(); msgQ.insertMessage(spaMessage); Figure 25. Writing the SPA Message
4. End the conversation using the version of insertMessage containing a boolean isLast argument set to true: msgQ.insertMessage(spaMessage, true);
Conversational Transaction Sequence of Events: When the message is a conversational transaction, the following sequence of events occurs: 1. IMS removes the transaction code and places it at the beginning of a message segment. The message segment is equal in length to the SPA that was defined for this transaction during system definition. This is the first segment of the input message that is made available to the program. The second through the nth segments from the terminal, minus the transaction code, become the remainder of the message that is presented to the application program. 2. When the conversational program has prepared its reply, it inserts the SPA to IMS. The program then inserts the actual text of the reply as segments of an output message. 3. IMS saves the SPA and routes the message to the input LTERM (logical terminal). 4. If the SPA insert specified that another program is to continue the same conversation, the total reply (including the SPA) is retained on the message queue as input to the next program. This program then receives the message in a similar form. 5. A conversational program must be scheduled for each input exchange. The other processing continues while the operator at the input terminal examines the reply and prepares new input messages. 6. To terminate a conversation, the program places blanks in the transaction code field of the SPA and inserts the SPA to IMS. In IMS Java this happens when you call IMSMessageQueue.insertMessage with the boolean parameter isLast set to true. 7. The conversation can also be terminated if the transaction code in the SPA is replaced by any non conversational program’s transaction code, and the SPA is inserted to IMS. After the next terminal input, IMS routes that message to the other program’s queue in the normal way.
Handling Multi-Segment Messages
| | | |
It is possible in message driven applications to have multi-segment input messages. That is, more than one message needs to be read from the message queue in order to retrieve the entire message. When this occurs, you must provide a
54
IMS Java User’s Guide
IMS Applications | |
mapping for each message that is to be read from the queue and use the appropriate methods available from the IMSMessageQueue class.
| | | | | | | | | | | | | | | | | | | | | | | | |
The following code defines two input messages that comprise a multi-segment message:
| | | | | | | | | | | | | | | | | | |
The following code illustrates how the message queue is used to retrieve both messages:
|
Coding and Accessing Messages with Repeating Structures
public class InputMessage1 extends IMSFieldMessage { final static DLITypeInfo[] segmentInfo = { new DLITypeInfo("Field1", DLITypeInfo.CHAR, 1, 10), new DLITypeInfo("Field2", DLITypeInfo.INTEGER, 11, 4) };
}
public InputMessage1() { super(segmentInfo, 14, false); }
public class InputMessage2 extends IMSFieldMessage { final static DLITypeInfo[] segmentInfo = { new DLITypeInfo("Field1", DLITypeInfo.CHAR, 1, 10), new DLITypeInfo("Field2", DLITypeInfo.CHAR, 11, 8) };
}
public InputMessage2() { super(segmentInfo, 18, false); }
//Create a message queue IMSMessageQueue messageQueue = new IMSMessageQueue(); //Create the first input message InputMessage1 input1 = new InputMessage1(); //Create the second input message InputMessage2 input2 = new InputMessage2(); try { //Read the first message from the queue messageQueue.getUniqueMessage(input1); ... //Read the second message from the queue messageQueue.getNextMessage(input2); ... } catch (IMSException e) { ... }
Messages with repeating structures can be defined using a subclass of DLITypeInfo called DLITypeInfoList. DLITypeInfoList allows you to define an array of repeating structures in one object instead of multiple, individual DLITypeInfo objects. DLITypeInfoList is an object that stores an array of DLITypeInfo objects along with a count of its occurrences, thus allowing an input message to contain nested repeating structures. Figure 26 on page 56 is an example of an output message containing a set of“ Make,”“ Model,” and “Color” fields, with a count field to identify how many occurrences were stored:
Chapter 4. Writing a Java Application Program
55
IMS Applications | | | | | | | | | | | | |
public class ModelOutput extends IMSFieldMessage { static DLITypeInfo[] modelTypeInfo = { new DLITypeInfo("Make", DLITypeInfo.CHAR, 1, 20), new DLITypeInfo("Model", DLITypeInfo.CHAR, 21, 20), new DLITypeInfo("Color", DLITypeInfo.CHAR, 41, 20), }; static DLITypeInfo[] modelTypeInfoList = { new DLITypeInfo("ModelCount", DLITypeInfo.INTEGER, 1, 4), new DLITypeInfoList("Models", modelTypeInfo 5, 60, 100), }; public ModelOutput() { super(modelOutputTypeInfo, 6004, false); } }
| |
Figure 26. Example Output Message
Note: The creation of the DLITypeInfoList object has no provision for specifying its type. DLITypeInfoList hard codes the type of the fields to DLITypeInfo.TYPELIST. This design is not constrained to any specific level of nesting. Within the declaration of model TypeInfo in Figure 26, any of the array members could be instances of DLITypeInfoList. To access the nested structures defined in a DLITypeInfoList, use a dotted notation for specifying the fields and the index of the field within a repeating structure. This dotted notation can use either the field names or field indexes. For example, the “Color” field in the fourth“ Models” definition in ModelOutput would be accessed as “Models.4.Color” within the Model Output message. The following code sets the fourth “Color” in the ModelOutput message to “Red.” ModelOutput output= new ModelOutput(); output.setString("Models.4.Color", "Red");
The following code uses field indexes instead of field names to make the same change to the ModelOutput message: ModelOutput output= new ModelOutput(); output.setString("2.4.3", "Red");
Because DLISegment objects are defined using DLITypeInfo objects exactly like IMSFieldMessages, you can also use these repeating structures within your definitions of DLISegment subclasses. If you do this, however, and you wish to use DLIModel, you will have to modify the generated classes from the utility. DLIModel will not use DLITypeInfoList definitions in its generated classes. However, you cannot access fields defined in this manner using an SQL query.
| | | | | |
Flexible Reading of Multiple Input Messages There are times when an application needs to process multiple input messages that require different input data types. For example, the car dealership sample application supports requests to list models, show model details, find cars, cancel orders, and record sales. Each of these requests requires different input data. The following steps show you how to define the messages to support these requests and how to access the messages from the application. The letters in the code samples (for example, A) are described on page 58. 1. Define the primary input message. This is the message you pass to IMSMessageQueue.getUniqueMessage to retrieve all of your input messages. Your primary input message must have an I/O area large enough to contain any of the input requests that your application might receive. It should also contain at least one field in common with all your input messages that allows you to determine the input request. In this example, the common field is
56
IMS Java User’s Guide
IMS Applications “CommandCode,” and the maximum length of each message is 64 (the number passed to the IMSFieldMessage constructor): public class InputMessage extends IMSFieldMessage { final static DLITypeInfo[] fieldInfo = { new DLITypeInfo("CommandCode", DLITypeInfo.CHAR, 1, 20), A }; public InputMessage(DLITypeInfo[] fieldInfo) {
}
super(fieldInfo, 64, false); B }
Figure 27. Defining the Primary Input Message
2. Define separate input messages for each request. Each of these input messages contains the same “CommandCode” field as its first field. Each of these input messages also uses an IMSFieldMessage constructor that takes an IMSFieldMessage and a DLITypeInfo array. This constructor allows you to remap the contents of the primary input message using the same type of information with each request; therefore, you do not copy the I/O area of the message, only a reference to this area. Figure 28 on page 58 illustrates code that created the input messages for the requests “ShowModelDetails,” “FindACar,” and “CancelOrder.”
Chapter 4. Writing a Java Application Program
57
IMS Applications public class ShowModelDetailsInput extends IMSFieldMessage { final static DLITypeInfo[] fieldInfo = { new DLITypeInfo("CommandCode", DLITypeInfo.CHAR, 1, 20), C new DLITypeInfo("ModelTypeCode", DLITypeInfo.CHAR, 21, 2), }; public ShowModelDetailsInput(InputMessage inputMessage) { D super(inputMessage, fieldInfo); } } public class FindACarInput extends IMSFieldMessage { final static DLITypeInfo[] fieldInfo = { new DLITypeInfo("CommandCode", DLITypeInfo.CHAR, 1, 20), E new DLITypeInfo("Make", DLITypeInfo.CHAR, 21, 10), new DLITypeInfo("Model", DLITypeInfo.CHAR, 31, 10), new DLITypeInfo("Year", DLITypeInfo.CHAR, 41, 4), new DLITypeInfo("LowPrice", DLITypeInfo.PACKEDDECIMAL, 45, 5), new DLITypeInfo("HighPrice", DLITypeInfo.PACKEDDECIMAL, 50, 5), new DLITypeInfo("Color", DLITypeInfo.CHAR, 55, 10), }; public FindACarInput(InputMessage inputMessage) { F super(inputMessage, fieldInfo); } } public class CancelOrderInput extends IMSFieldMessage { final static DLITypeInfo[] fieldInfo = { new DLITypeInfo("CommandCode", DLITypeInfo.CHAR, 1, 20), G new DLITypeInfo("OrderNumber", DLITypeInfo.CHAR, 21, 6), new DLITypeInfo("DealerNumber", DLITypeInfo.CHAR, 21, 6), }; public CancelOrderInput(InputMessage inputMessage) H { super(inputMessage, fieldInfo); }
Figure 28. Creating the Input Messages
Note the following about Figure 28: v The CommandCode field is defined within every class at lines A, C, E, and G. This field must be defined in every message that reads the command code. If you do not define the field, you must adjust the offsets of the following fields to account for the CommandCode’s existence in the byte array. For example, you can delete the DLITypeInfo entry for “CommandCode” in CancelOrderInput, but the “OrderNumber” field must still start at offset 21. v The length of the base class, InputMessage, must be large enough to contain any of its subclasses. In this example, InputMessage is 65 bytes because the fields of FindACarInput require it B. v Each InputMessage subclass must provide a constructor to create itself from an InputMessage, as in lines D, F, and H. This constructor uses a new constructor in IMSFieldMessage, called a copy constructor.
58
IMS Java User’s Guide
IMS Applications Given this design, an application can provide message reading logic similar to Figure 29. while (getUniqueMessage(inputMessage)) { string commandCode=inputMsg.getString("CommandCode").trim(); if (commandCode.equals("ShowModelDetails")) { showModelDetails(new ShowModelDetailsInput(inputMessage)); } else if(commandCode.equals("FindACar")) { findACar(new FindACarInput(inputMessage)); } else { //process an error } }
Figure 29. Message Reading Logic
CICS Applications The following programming model outlines the supported structure for CICS applications that use IMS Java. The models are not complete, but show the normal flow of the application for both the JDBC and SSA access methods. This model use JDBC, but for the IMS Java hierarchic database interface method, database access happens in the same places in the program flow as with JDBC. public static void main(CommAreaHolder cah) { conn = DriverManager.getConnection(...);
//Receives control //Establish DB connection
repeat { results = statement.executeQuery(...); //Perform DB processing ... //send output to terminal }
}
conn.close(); return;
//Close DB connection
DB2 Stored Procedures The following programming model outlines the supported structure for DB2 Stored Procedures that use IMS Java. The models are not complete, but show the normal flow of the application for both the JDBC and SSA access methods. This model use JDBC, but for the IMS Java hierarchic database interface, database access happens in the same places in the program flow as with JDBC. public static void targetMethod(...) {
//Receives control with //input or output parameters
conn = DriverManager.getConnection(...);
//Establish DB connection
repeat { results = statement.executeQuery(...); //Perform DB processing ... } partmOut[...]=...;
//Move results to output //parameters Chapter 4. Writing a Java Application Program
59
IMS Applications
}
60
IMS Java User’s Guide
conn.close(); return;
//Close DB connection
| |
Chapter 5. DLIModel Utility
| |
This chapter contains information on the DLIModel utility including introductory and practical usage information.
| | | | | | |
In This Chapter: v “DLIModel Utility Overview” v “Requirements and Restrictions of the DLIModel Utility” on page 63 v “Output Types of the DLIModel Utility” on page 64
| |
v “Control Statements for the DLIModel Utility” on page 66 v “Running the DLIModel Utility” on page 74 v “Examples of Using the DLIModel Utility” on page 77
DLIModel Utility Overview
| | | |
Processing IMS databases with an IMS Java application requires that you describe the database view of your application’s PSB to IMS Java. You must do this by providing the name of a metadata class when establishing the JDBC database connection.
|
There are two ways you can prepare the metadata class for an application: v Provide the application PSB source and any related DBD source to the DLIModel utility, and specify the generation of the IMS Java metadata class.
| | | | | |
This is the recommended technique and is described in this chapter. v Code the metadata class manually. This is described further in Appendix A, “Manually Creating IMS Java Metadata Classes” on page 99.
| | | | | | | | | | |
You can use the DLIModel utility to: v Create IMS Java metadata classes to describe a PSB’s view of IMS databases, from PSB and DBD source. v Incorporate additional field information from XMI input files that describe COBOL copybook members. v Incorporate additional PCB, segment, and field information, or overrides of existing information, into the generated class from user-prepared input control statements. v Create a DLIModel Java Report (designed to assist Java application programmers), which describes the IMS Java view of the PSB and its databases.
| | | | | | |
The DLIModel utility can process most types of PSBs and databases. For example, IMS Java supports: v All database organizations except MSDB, HSAM, SHSAM, and GSAM
v Create an XMI description of the PSB and its databases.
v All types and implementations of logical relationships v Secondary indexes except for shared secondary indexes v Secondary indexes processed as stand-alone databases v PSBs that specify field-level sensitivity
|
© Copyright IBM Corp. 2000, 2002
61
DLIModel Utility Overview |
| | | | | | | |
Figure 30. The DLIModel Utility Inputs and Outputs
Figure 30 shows the inputs and outputs of the DLIModel utility. The actions of the utility are directed by control statements that you supply. PSB and DBD source members are read from their PDS or PDSE data sets and parsed by the utility to build an in-memory object model of the database structure and the PSB’s view of that structure. Multiple PSBs may be processed in a single run of the utility. The control statements can specify: v Which PSBs to process in this run v Aliases for PSBs, PCBs, segments, and fields
| | | | | | | |
v Data types and format masks for fields v XMI files that contain XMI descriptions of COBOL copybook members corresponding to segments v Additional field definitions for fields that were not defined in the DBD or COBOL copybook XMI file v Information that overrides PSB, DBD, and COBOL copybook XMI information
| |
v Default values for newly inserted segments When these inputs have all been processed and incorporated into the model, the utility generates various outputs that were requested through control statements.
| |
62
IMS Java User’s Guide
DLIModel Utility Overview | | |
You can request to have an IMS Java metadata class be generated for each PSB processed, together with a corresponding easy-to-read DLIModel Java Report for the Java programmer to use.
| | |
You can request an XMI description of the entire in-memory model (one description covers all PSBs and DBDs processed in the run). For details of this XMI output, see “XMI Description of the Databases” on page 65.
| |
You can also request a detailed trace file of the utility execution if one is necessary for problem resolution.
| |
Requirements and Restrictions of the DLIModel Utility
|
Requirements The following are the requirements to run the DLIModel utility. v PCBs in the PSB must be named, either through statement labels or the PCBNAME parameter. v If your application uses JDBC and the field list in a call includes fields from more than one segment in a hierarchic path, then IMS Java employs path calls. In this case you must include the PROCOPT=P option in the PCB or SENSEG statements, as appropriate. v If your application uses SSA database access, path calls are under your control, and you must choose PSB processing options depending on your processing, in the usual way.
| | | | | | | | | | | | | | | | | | | |
v This utility will not validate the PSB and DBD source. IBM strongly recommends that you generate DBDs, PSBs, and ACBs, correct all errors, and then run the DLIModel utility. v This utility follows all inter-DBD references when building its model, and may require access to DBDs that are not directly referenced by PCBs in the PSB. For example, when processing a PSB that references a main database with a number of secondary indexes, DLIModel needs access to the secondary index DBDs even if the PSB does not explicitly name any of these indexes for a secondary processing sequence, or for segment search purposes. Similarly, all DBDs related by logical relationships must be accessible. v You must maintain the length field in variable length segments on INSERT or UPDATE. v XMI input files must conform to the COBOL metamodel, which is part of the CAM metamodel of the OMG-accepted version of the UML specification for the Enterprise Application Integration (EAI) standard.
| | | | | | | | | | | | | |
Restrictions The DLIModel utility has the following restrictions. It cannot process: v MSDB, HSAM, SHSAM, and GSAM databases v Shared secondary indexes v PROCOPT=K option in a PSB SENSEG v The DLIModel utility does not use DLITypeInfoList classes in its generated classes. If you want to define repeating groups of fields in segments (other than by explicitly defining each group of fields separately) you will have to create the classes manually or modify the classes generated by DLIModel.
Chapter 5. DLIModel Utility
63
DLIModel Utility Overview | | |
v COBOL copybook XMI files, which supply additional information about field layouts, must describe the physical segments. The files cannot describe the logical database segment layouts.
| | |
Related Reading: For more information about IMS hierarchical databases, see the:IMS Version 7 Administration Guide: Database Manager and the IMS Version 7 Utilities Reference: System.
| |
Output Types of the DLIModel Utility This section discusses the different output types of the DLIModel utility.
| |
IMS Java Metadata Classes
| | |
The DLIModel utility produces the necessary metadata classes needed to develop IMS Java applications. However, the Java developer needs only to reference the DLIModel Java Report for information about the classes.
| |
Related Reading: For a description of the class source produced, refer to the Appendix A, “Manually Creating IMS Java Metadata Classes” on page 99.
|
DLIModel Java Report
| | | |
The DLIModel Java Report summarizes the structure of the IMS databases in a way that allows you to create IMS Java applications and to code SQL queries against the databases. With the DLIModel Report, you do not have to interpret the syntax of the IMS Java classes or refer to the DBD or PSB source.
| |
Related Reading: Sample DLIModel Java Reports are shown in each of the four examples in “Examples of Using the DLIModel Utility” on page 77.
| | | | | | |
PSB Description
| | | | |
PCB Description
| | | | | |
Segment Description
| | | |
Field Description
Within the DLIModel Java Report, a separate section is produced for each PSB named in a PSB statement of the control data set. The name of the generated class for the PSB is given first, which is either the name defined by the JavaName parameter or, if no JavaName is specified, the 8-character IMS PSB name. The report also gives the IMS PSB name and the package for this class, if one was specified in the OPTIONS control statement. Within each PSB, sections are listed for each PCB. Each PCB is identified by its IMS Java name, which is either the user-chosen JavaName, if one was specified, or the 8-character IMS PCB name. This is the PCB name that should be used in SQL queries to the database. Within each PCB, all segments are listed in hierarchical sequence. Segment descriptions are indented to illustrate the hierarchical dependencies. Each segment is identified by its IMS Java name, which is either the JavaName, if one was specified in the control data set, or the 8-character IMS Segment name. Use the IMS Java name for the segment in SQL queries to the database. Within each segment, fields are listed in the order in which they appear in the database DBD with any additional fields appended. Fields are of the following types:
64
IMS Java User’s Guide
DLIModel Utility Outputs | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Field that is physically resident in a DBD A field that is physically resident in a DBD is identified by its IMS Java name, which is either the user-chosen JavaName, if one was specified, or the 8-character IMS Field name. This is the name that should be used in SQL queries. A DBD field is further annotated as either a ++ Primary Key Field ++ if it is the sequence field of its segment, or a (Search field) if it is a non-sequence field. SQL queries with WHERE clauses qualified on Primary Key Fields will generally produce much faster response times than calls qualified on search fields, but both are allowed. These fields have their IMS Java type listed, and if necessary, their type qualifier string. They also have their Start position and Bytes listed. It is important to note that the Start and Bytes values describe the field’s properties in the original database segment, not necessarily its Start or Bytes as viewed from Java application. The primary purpose of the Start and Bytes values is to describe how these fields overlap or redefine each other in the database. They are otherwise unnecessary for writing SQL queries in the Java application. DBD secondary index search field A DBD secondary index search field (a field defined in the DBD with an XDFLD macro) is also identified through its IMS Java name, either user-chosen, or the DBD name. The field is annotated as ++ Secondary Key Field ++, and like a ++Primary Key Field ++ will produce fast responses to queries. However, secondary index search fields are not physically present in their segment and can not be retrieved from the Java ResultSet. In the report, secondary index search fields are followed by a list of their component search fields to assist you in creating a suitable string to use as a search argument in an SQL query. A secondary index field has no Start or Bytes value in the segment. It is essentially a virtual field and is used for search purposes only. Field that is not present in the DBD A field that is not present in the DBD is identified (for example, one that has been added by a Field control statement or by an XMI COBOL copybook description) by its Java name, if one is present, or by its 8-character name. Its start position, length, data type, and type qualifier are all listed. It has no key field or search field annotation in the report, indicating that it may not be used in an SQL WHERE clause. However, it may be retrieved from the result set following successful queries.
XMI Description of the Databases
| | | |
An XMI file, written in UTF-8 encoding, is produced by the utility if you specify genXMI=YES in the OPTIONS control statement. It describes all of the PSBs and their referenced DBDs processed in the entire run of the utility. DBDs shared by multiple PSBs or PCBs are only described once.
| | | | |
Samples of the XMI produced (converted from UTF-8 to EBCDIC encoding for viewing in an OS/390 environment) for each of the samples in this chapter are in the samples directories. To use a sample XMI file as input for an application, convert the file back to UTF-8 encoding. You can also run the utility using the sample input files to generate XMI files written in UTF-8 encoding.
| |
The XMI that is produced by the utility is based on a meta-model of IMS database defined in UML. This model is a package with a number of inheritance relationships
Chapter 5. DLIModel Utility
65
DLIModel Utility Outputs | |
to the OMG Common Warehouse Metamodel (CWM). However, only the IMS package itself is included and used in the DLIModel utility.
| | | | | | |
Directory /usr/lpp/ims/imsjava71/samples/dlimodel/model of the distribution media contains: v An EBCDIC-encoded XMI definition of the meta-model to view in an OS/390 environment. v A Rational Rose model file of the meta-model. This model file is at the 4.5/6.0 Model level, corresponding to Rose 98 or 98i. To view this file, you need a licensed and installed copy of a suitable level of the Rational Rose product.
|
DLIModel Trace The DLI Model utility can generate a trace file, named dlimodeltrace, if you need to resolve a problem with the utility. For the utility to generate the trace file, specify GenTrace=YES in the OPTIONS statement. You can also specify the path where the file is written by using the TracePath parameter.
| | | | | |
Control Statements for the DLIModel Utility
| | | | |
You must write control statements to specify certain options such as input and output data set names, and what PSBs and PCBs to use. You can also use the control statements to supply information to the utility about PSBs, PCBs, segments, and fields that cannot be extracted from the PSBs, DBDs, or COBOL copybook XMI files.
| | |
The control statements are supplied to the utility in a PDS member named in the EXEC statement PARM field of the MVS JCL, or in an HFS file named in a command line parameter in the MVS USS environment.
|
Control Data Set Rules
| |
You must include at least the following statements in your control statement data set:
| |
v OPTIONS Statement v PSB Statement for each PSB to be processed
|
Optionally, you can include the following statements in the control data set:
| |
v PCB Statement v SEGM Statement
| | |
v FIELD Statement v XDFLD Statement v INCLUDE Statement
| |
The following syntax diagram shows how to organize the control statements in the control data set.
| | QQ
|
66
IMS Java User’s Guide
OPTIONS Statement
\
PSB Statement
\ PCB Statement
Q
DLIModel Utility Control Statements | |
Q \ SEGM Statement
| |
\
Q
\ FIELD Statement
XDFLD Statement
Q \
QT INCLUDE Statement
| | | |
If you requested IMS Java metadata class source in the OPTIONS statement, each PSB that you specified results in a separate metadata .java file, and a corresponding DLIModel Java Report.
| | | | | |
A typical reason to include PCB, SEGM, and FIELD statements is to assign to these entities a customized name (referred to as an alias) that can be used in your Java program. You can choose a name that is more meaningful than the 8-character name given to these entities in the DBD and PSB source. You might also need to assign data types to fields, and to define additional fields that are important to your application but that were not defined in the segment in the DBD.
| | | | |
You do not need to include PCB, SEGM, or FIELD statements in your control statement set if all of the following statements are true of your application:
| |
Related Reading: For examples of control statement sets, refer to the examples in “Examples of Using the DLIModel Utility” on page 77.
| | |
The rules for ordering the control statements are as follows: v The OPTIONS statement must be first and only be present in a top-level control data set. v PCB statements must follow immediately after the PSB statement to which they belong. They may be in any order (for example, PCB statements need not be in the same order as they appear in the original PSB source).
| | | | | | | | | | |
v It can process PCBs, segments and fields by their 8-character IMS names. v It needs only fields that are defined in the DBD. v All fields can be processed as data type CHAR.
v FIELD statements must follow immediately after the SEGM for the physical segment to which they belong. However, Field statements may be in any order within their segment group. (for example, field statements need not be in the same sequence as they appear in the original DBD source)
| |
FIELD statements for existing fields and for new fields may be intermixed or grouped in any sequence. v INCLUDE statements can be positioned anywhere in a control data set, but not between: – PSB statement and any PCB statements that belong to it – SEGM statement and any FIELD statements that belong to it
| | |
You can nest multiple control data sets by using the INCLUDE statement. Nesting gives you the flexibility to store your control statements across multiple HFS files or PDS members for increased convenience and control.
| |
For example, a top-level file could contain the OPTIONS, PSB and PCB statements that specify a desired Java-class generation. Included files might each contain a Chapter 5. DLIModel Utility
67
DLIModel Utility Control Statements group of SEGM and FIELD statements that relate to an individual logical or physical DBD. You can reuse these latter files without change for other PSBs that reference the same databases and segments.
| | | |
Control Statement Rules
| | | | |
The control statement syntax is very flexible. Each statement consists of an identifier followed by keyword parameters. The identifier may start in any column. Each identifier, keyword, and variable must be separated by at least one whitespace character, unless it is already separated by an operator. Keyword parameters can occur in any order.
| | | |
If your control statements are held in an MVS data set, map the statements to multiple 80-character records, between columns 1 and 72 inclusive. Columns 73 through 80 are ignored, and may be used for sequence numbers if you wish. No continuation characters are required.
| | | |
If your control statements are held in an HFS file, any line length is acceptable, but you can optionally continue statements across multiple lines as in MVS. If you restrict your line length to less than 73 characters, your control statements can be moved between MVS data sets and HFS files without change.
| | |
Identifiers, parameter keywords, and predefined parameter values (such as, YES and NO) may appear in upper or lower case. Other parameter values (for example, user specified path or Java names) are case sensitive.
|
Control Statement Syntax
| | | |
OPTIONS Statement
|
The following diagram shows the syntax of the OPTIONS statement.
One OPTIONS control statement is required. The statement customizes the DLIModel utility by specifying where to find input, what output to produce, and where to put the output.
| |
QQ OPTIONS \ PSBds= IMS.qual.dsname(member)
| |
Q
Q \ DBDds= IMS.qual.dsname(member)
Q Package=
GenJavaSource=
| |
NO
GenXMI=
NO
packagename GenTrace=
NO Q
Q GenJavaSource=
YES
GenXMI=
YES
GenTrace=
Q
Q
| |
OutPath= path
|
68
IMS Java User’s Guide
YES
JavaSourcePath=
path
ReportPath=
path
DLIModel Utility Control Statements FieldOrder=
|
DEFAULT
Q
QT XMIPath= path
TracePath=
path FieldOrder=
OFFSET
| | | | | |
PSBds=IMS.qual.dsname(member) Required parameter specifies the data set name of the PSB source. If multiple parameters are specified, the utility opens and searches the data sets in the order of the PDSds parameters when it is reading a PSB. This action is similar to data set concatenation in an MVS JVL DD statement.
| | | | |
DBDds=IMS.qual.dsname(member) Required parameter specifies the data set name of the DBD source. If multiple parameters are specified, the utility opens and searches the data sets in the order of the DBDds parameters when it is reading a DBD. This action is similar to data set concatenation in an MVS JVL DD statement.
| | |
Package=packagename Optional parameter specifies the package that the generated IMS Java classes are for. A Java package statement is added to each .java file produced.
| | |
GenJavaSource=YES | NO Optional parameter specifies whether to generate IMS Java class source files and a DLIModel Java report.
| | | |
GenXMI=YES | NO Optional parameter specifies whether to generate an XMI file (dlimodelxmi.xmi) that describes the database model based on all PSBs and corresponding databases processed by the utility.
| | |
GenTrace=YES | NO Optional parameter specifies whether to generate a trace file (named dlimodeltrace) of the utility run.
| | | |
OutPath=path Optional parameter specifies the HFS directory where the utility writes the output files, unless you specify path names for specific output files. The default is the current directory.
| | |
JavaSourcePath=path Optional parameter specifies the HFS directory where the utility writes the IMS Java class files. Overrides OutPath.
| | |
ReportPath=path Optional parameter specifies the HFS directory where the utility writes the DLIModel Java report. Overrides OutPath.
| | |
XMIPath=path Optional parameter specifies the HFS directory where the utility writes the generated XMI. Overrides OutPath.
| | |
TracePath=path Optional parameter specifies the HFS directory where the utility writes the trace file. Overrides OutPath.
| | |
FieldOrder=DEFAULT | OFFSET Optional parameter specifies the order of the fields of segments in the generated IMS Java class.
Chapter 5. DLIModel Utility
69
DLIModel Utility Control Statements | | |
DEFAULT Fields are in the same order as in the DBD and followed by any new fields defined by the control statements.
| |
OFFSET Fields are in the order their start positions.
| | |
PSB Statement
|
The following diagram shows the syntax of the PSB statement.
|
QQ PSB
The PSB statement is required because it defines which PSBs that the utility uses. Multiple PSB statements are allowed, unless the * wildcard form is specified.
PSBName=
name nameprefix* *
QT JavaName=
name
| PSBName=name | nameprefix | * Required parameter specifies the PSB to be used by the utility.
| | | |
name Process the PSB with the name name.
| | |
nameprefix* Process all PSBs with the nameprefix in the specified PSB data set input file.
|
*
Process all PSBs in the specified data set input file.
| | |
JavaName=name Optional parameter specifies the name of the generated IMS Java class only if using one PSB. Ignored if using nameprefix or ALL for PSBName.
| | |
PCB Statement
|
The following diagram shows the syntax of the PCB statement.
| |
QQ PCB
| | |
PCBName=name Required parameter specifies the eight-character PCB name that you want to assign an alias to.
| | |
JavaName=name Required parameter specifies the Java alias for the PCB, which will be used in the Java application. Must be unique for each PSB.
| | |
SEGM Statement
| |
For physical segments, the SEGM statement: v Identifies a physical segment in a DBD v Optionally supplies a Java alias for the segment v Specifies an XMI COBOL copybook file containing additional information about the segment
The PCB statement is optional. It specifies a Java alias for a PCB. All PCB statements for a PSB must follow the PSB statement.
PCBName= name
JavaName=
name
The SEGM control statement is optional and used for physical and logical segments.
| | |
70
IMS Java User’s Guide
QT
DLIModel Utility Control Statements |
v Groups the FIELD statements that follow the SEGM statement
|
For logical segments, the SEGM statement:
| | |
v Identifies a logical segment in a logical DBD v Specifies a Java alias for the segment v Cannot be followed by any FIELD statements
| | | | |
If the utility cannot find the segment, it issues a warning (instead of an error) and ignores any following FIELD statements. Because the utility only issues an error, you can create control statement files that provide information about many segments and their fields, not all of which are used by the particular PSB being processed.
| |
If an XMI COBOL copybook file was named for a segment, the fields that it defines are merged by name with the fields defined in the DBD.
|
The following diagram shows the syntax of the SEGM statement.
|
QQ SEGM DBDName= name SegmentName= name JavaName= name
QT
XMIName= name
| | | |
DBDName=name Required parameter specifies the eight-character DBD name where the segment is defined.
| |
SegmentName=name Required parameter specifies the segment name in the DBD.
| | | |
JavaName=name Required parameter specifies the Java alias for the segment, which will be used in the Java application. Must be unique for each DBD. If specified, overrides any value that might have been set from a COBOL XMI file.
| | | |
XMIName=name Optional parameter specifies the name of an XMI COBOL copybook file that may provide additional information about the segment and its existing fields, and definitions of new fields. XMI input is only allowed for physical segments.
| | | | |
FIELD Statement
| | | | |
When adding information for an existing DBD field, you must specify the 8-character DBD name of the field using the Name parameter. You can optionally specify the starting position (Start parameter) and length (Bytes parameter) of the field. If you do, DLIModel checks these values against the DBD and produces an error message if they do not match.
| | | | |
To add information to a non-DBD field that has been inputted from COBOL copybook XMI file, specify a Java name (JavaName parameter) that matches the name of the copybook field. Do not specify a DBD 8-character field name (Name parameter). Not specifying a Name parameter, for example, to add a default value to a COBOL copybook field.
The FIELD statement is optional. It specifies information about a field or defines a new field for a segment in a physical DBD. All FIELD statements for a segment must immediately follow the SEGM statement. However, FIELD statements can be in any order and mixed with XDFLD statements.
Chapter 5. DLIModel Utility
71
DLIModel Utility Control Statements | | | | |
To define a new field in the segment, do not specify a DBD 8-character field name. Instead, specify a unique Java name (JavaName parameter) that does not match any Java field name in the segment. You must also specify a starting position (Start parameter) and a length (Bytes parameter) for the new field. You can include other attributes (for example, data type or default value) for the new field.
| | |
To define a new field, you must specify the starting position (Start parameter), the length (Byte parameter) of the field, and the name (Name or JavaName parameter) of the field.
|
The following diagram shows the syntax of the FIELD statement.
| |
QQ FIELD
| |
Q
| | |
Q
| | | |
Name=name Specifies eight-character field name as defined in the DBD. Must be unique within segment. Identifies this control statement as applying to an existing field within the DBD. Do not specify this parameter if you are specifying a new field.
| | |
Start=int Specifies the starting position of the field in the segment. The first byte in the segment is 1. Required for new fields and optional for existing fields.
| | |
Bytes=name Specifies the length of the field in the segment. Required for new fields and optional for existing fields.
| | | | | | |
JavaName=name Specifies the Java alias for the field. Java names of Field statements and XDFLD statements must be unique within a segment. Required if defining a new field and optional for existing fields. If a field has been inputted from COBOL copybook XMI file with the same name as the JavaName parameter on a control statement, the control statement is applied to this COBOL copybook field.
| | | | | | | | | | | | | | | |
JavaType=string Optional parameter specifies the Java type of the field. Default is CHAR. Allowed types: CHAR FLOAT DOUBLE SMALLINT INTEGER BIGINT ZONEDDECIMAL TIME CARCHAR TINYINT BIT TYPELIST BINARY
Q Name= name
Start=
int
Bytes=
name Q
JavaName= name
JavaType=
string
TypeQualifier=
string QT
Default= string
72
IMS Java User’s Guide
DLIModel Utility Control Statements | | |
PACKEDDECIMAL DATE TIMESTAMP
|
Overrides any value that was set by the XMI COBOL copybook file.
| | | | | | | |
TypeQualifier=string Required parameter for some Java types. Specifies type qualifier for the following Java types: PACKEDDECIMAL ZONEDDECIMAL DATE TIME TIMESTAMP
| |
Related Reading: For more information on determining the syntax of type qualifiers, see “Supported Data Types in IMS Java” on page 32.
| | | | |
Default=string Optional parameter specifies the default value for the field. The default value is used for new instances of the segment when an application does not define a value for the field. The string must be formatted to match the data type qualifier properties of the field.
| | | |
XDFLD Statement
| | | | | |
You must identify a secondary index field (which must be an existing field that was defined in the DBD) by the eight-character name because secondary index fields do not have a starting position in the segment. Secondary index fields do not have a data type. Therefore, you must create a single string that contains the concatenated search fields, each correctly encoded for its data type, when using the index field in a JDBC Select. An index field cannot be fetched from the JDBC Resultset.
|
The following diagram shows the syntax of the XDFLD statement.
| |
QQ XDFLD
| | |
Name=name Required parameter specifies the eight-character name of the secondary index field as defined in the DBD.
| |
JavaName=name Required parameter specifies the Java alias for the field.
| | | | | |
INCLUDE Statement
| | | |
Important: Do not put an INCLUDE statement between PSB statements and PCB statements or between SEGM statements and FIELD statements. Putting the INCLUDE statement between these statements breaks the required relationship between them.
The XDFLD statement is optional. It specifies a Java alias for an existing secondary index field in a segment. The DXFLD statements must follow the SEGM statement that corresponds to the segment with the secondary indexes in the DBD.
Name= name
JavaName=
name
QT
The INCLUDE statement is optional and is only allowed in the top-level control statement data set. It specifies a PDS member or HFS file of additional control statements to be included in the top-level data set. The included data set must be the same type (PDS or HFS) as the top-level data set. You are allowed any number of INCLUDE statements in the top-level data set.
Chapter 5. DLIModel Utility
73
DLIModel Utility Control Statements |
The following diagram shows the syntax for the INCLUDE statement.
|
QQ INCLUDE
Dataset=
IMS.qual.dsname(member) path/filename
QT
| | | |
Dataset=IMS.qual.dsname(member) | path/filename Required parameter specifies the PDS member of HFS file containing the control statements that are to be included in the top-level data set.
| | | |
Comment Statement
| |
The Comment Statement is optional. It indicates that a line in the PDS member is a comment the same way as you would do in Java code. For example: // The two slashes indicate that this line is a comment.
Running the DLIModel Utility You can run the DLIModel utility either as a standard OS/390 MVS job, or from the command prompt under MVS Unix System Services (USS). For the latter alternative, see “Running the DLIModel Utility From MVS Unix Systems Services” on page 77.
| | | | |
Running the DLIModel Utility as an MVS Job
| | | | | | |
An MVS procedure is provided in order to run DLIModel as an MVS job. This procedure must initially be moved from its distribution library (where it is named, DFSMODEL) to the procedure library from which your installation executes IMS database utilities. It must be tailored to your installation’s requirements, and optionally renamed to a name of your choosing. See “DLIModel Utility Setup” on page 19. This book assumes that you have renamed the procedure to DLIMODEL (all upper case).
| | |
Since the DLIModel utility is a Java application, the DLIMODEL procedure runs it on OS/390 using BPXBATCH, an MVS-provided utility that runs any OS/390 UNIX shell command or executable.
|
The DLIMODEL procedure has two steps: v Step 1 executes the DLIModel utility (a Java application) by invoking the MVS utility BPXBATCH. The data set name of a PDS control data set is provided to the utility through the EXEC statement PARM field. This step contains DD statements for the utility’s standard output steams, STDOUT and STDERR, which are directed to temporary HFS files. Other utility inputs and outputs are read from, or sent to data sets and files with names specified by the control data set, and do not have DD statements. v Step 2 redirects STDOUT and STDERR to MVS SYSOUT streams where they can be viewed using your usual procedures, for example, using SDSF.
| | | | | | | | |
The following is the DLIMODEL procedure, which runs the DLIModel utility:
| |
74
IMS Java User’s Guide
Running the DLIModel Utility | | | | | | | | | | | | | | | | | | | | | | | | | | |
//DLIMODEL PROC DSNAME=,SOUT=’*’ //******************************************************************** //* THIS PROC RUNS THE IMS JAVA UTILITY IN BATCH MODE //******************************************************************** //STEP1 EXEC PGM=BPXBATCH, // PARM=’SH "/usr/lpp/ims/imsjava71/dlimodel/go" "&DSNAME"’ //STDENV DD DUMMY //STDOUT DD PATH=’/tmp/&SYSUID..out’, // PATHOPTS=(OWRONLY,OCREAT,OTRUNC), // PATHMODE=SIRWXU //STDERR DD PATH=’/tmp/&SYSUID..err’, // PATHOPTS=(OWRONLY,OCREAT,OTRUNC), // PATHMODE=SIRWXU //*---------------------------------------------//* Redirect stdout and stderr output to SYSOUT: //STEP2 EXEC PGM=IKJEFT01,DYNAMNBR=300,COND=EVEN //SYSTSPRT DD SYSOUT=&SOUT //HFSOUT DD PATH=’/tmp/&SYSUID..out’ //HFSERR DD PATH=’/tmp/&SYSUID..err’ //STDOUTL DD SYSOUT=&SOUT,DCB=(RECFM=VB,LRECL=133,BLKSIZE=137) //STDERRL DD SYSOUT=&SOUT,DCB=(RECFM=VB,LRECL=133,BLKSIZE=137) //SYSPRINT DD SYSOUT=&SOUT // PEND
Figure 31. Sample DLIModel Utility PROC
|
PROC Statement Parameters
| |
DSNAME The name of the control data set for the utility
|
SOUT Sets the class for all SYSOUT output in the procedure.
|
Step 1 EXEC Statement Parameters
| |
PGM=BPXBATCH Runs the MVS BPXBATCH utility.
|
PARM Runs the utility as a Java application under the UNIX shell.
| |
/usr/lpp/ims/imsjava71/dlimodel/go is the path and file name of an HFS script file.
| | | | | |
DSNAME is a string parameter containing the fully qualified data set name of the top-level control data set, which contains the DLIModel utility control statements (as described in section “Control Statements for the DLIModel Utility” on page 66). DSNAME must refer to an MVS partitioned data set member. The format is: qual1.qual2.dsname(member)
|
The named data set should be F or FB type with an LRECL=80.
|
Step 1 DD Statements
| | |
STDENV DD Contains statements that set the Java environment variables. You should not need to use this DD statement.
| | | |
STDOUT DD The destination to which the utility in STEP 1 directs standard output. This includes messages recording the normal execution of the utility. This output is redirected by STEP 2 to the standard MVS SYSOUT destination. Chapter 5. DLIModel Utility
75
Running the DLIModel Utility | | | | |
STDERR DD The destination to which the utility in STEP 1 directs standard error output. This includes error and warning messages related to the execution of the utility. This output is redirected by STEP 2 to the standard MVS SYSOUT destination.
| | |
SYSTSIN DD Provides control cards for the MVS utility IKJEFT01 to copy the temporary HFS output files to the MVS SYSOUT destination.
|
Step 2 EXEC Statement Parameters
| | |
PGM=IKJEFT01 Runs the MVS utility IKJEFT01, which redirects STDOUT and STDERR to MVS SYSOUT.
| | |
DYNAMNBR See OS/390: Unix Systems Services User’s Guide and OS/390: Unix Systems Services Command Reference.
| | |
COND See OS/390: Unix Systems Services User’s Guide and OS/390: Unix Systems Services Command Reference.
|
Step 2 DD Statements
| |
SYSTEPRT DD IKJEFT01 utility output.
| |
HFSOUT DD Input from the temporary STDOUT file from step 1.
| |
HFSERR DD Input from the temporary STDERR file from step 1.
| |
STDOUTL DD Output destination for the STDOUT stream.
| |
STDERRL DD Output destination for the STDERR stream.
| |
SYSPRINT DD IKEJEFT01 utility output.
| | | | | |
SYSTSIN DD Must be added to execution JCL. Provides control statement input for the IKJEFT01 utility that redirect HFSOUT and HFSERR streams to the STDOUL and HFSERRL destinations. For example:
| | | | | |
As provided, the utility expects that you specify an HFS script file, /usr/lpp/ims/imsjava71/dlimodel/go, in its PARM= field. For details on whether this script file is required in your installation, how to prepare it, and alternatives, see “DLIModel Utility Setup” on page 19. Note that if a script file is required, its preparation is a one-time task. Once prepared it will be effectively invisible to users submitting the utility to MVS from ISPF.
| | |
Related Reading: For more information about the MVS BPXBATCH utility, see OS/390: Unix Systems Services User’s Guide and OS/390: Unix Systems Services Command Reference.
OCOPY INDD(HFSOUT) OUTDD(STDOUTL) OCOPY INDD(HFSERR) OUTDD(STDERRL)
76
IMS Java User’s Guide
Running the DLIModel Utility | | | | | | | | |
The following JCL an example of a job that runs the DLIMODEL procedure:
| |
In this example, the IKJEFT01 SYSTSIN DD statement is provided with control cards to copy the temporary HFS outputs to MVS SYSOUT destinations.
|
//BPXAUTP6 JOB CLASS=Z,MSGCLASS=E,MSGLEVEL=(1,1), // TIME=(9),USER=OMVSADM,PASSWORD=xxxxxxx, // REGION=32M //TEST EXEC DLIMODEL,DSNAME=’DQEIVP.ECDEV37.JCL(CNTRSTMT)’ //STEP2.SYSTSIN DD * OCOPY INDD(HFSOUT) OUTDD(STDOUTL) OCOPY INDD(HFSERR) OUTDD(STDERRL) /*
Running the DLIModel Utility From MVS Unix Systems Services
| | | | |
In addition to the JCL PROC, you can run the DLIModel utility from a prompt under MVS Unix System Services (USS). You can use this method if you are more familiar with a Unix environment than with MVS JCL or ISPF. See “DLIModel Utility Setup” on page 19 for recommendations on adjusting your shop’s Java environment for running the DLIModel utility as a Java application.
|
The command syntax for running the utility as a Java application is as follows:
| |
QQ java
| |
java Runs JDK 1.3.1 java command
| |
com.ibm.ims.metagen.DLIModel Main class of the DLIModel utility
| |
path/ControlFile HFS file for control data set
| |
com.ibm.ims.metagen.DLIModel path/ControlFile
QT
Examples of Using the DLIModel Utility
| |
The section shows examples of how the DLIModel utility uses DBDs, PSBs, control statements, and JCL to create IMS Java classes and DLIModel Java reports.
| | | | |
The examples in this section are in the following directories:
| | | | |
/usr/lpp/ims/imsjava71/samples/dlimodel/example1/ /usr/lpp/ims/imsjava71/samples/dlimodel/example2/ /usr/lpp/ims/imsjava71/samples/dlimodel/example3/ /usr/lpp/ims/imsjava71/samples/dlimodel/example4/
Example 1. Simple Example Figure 32 on page 78 shows a DBD for a single physical database with two segments. It is referenced by the PSB, with a single PCB and two sensitive segments shown in Figure 33 on page 78.
Chapter 5. DLIModel Utility
77
DLIModel Utility Examples DBD
NAME=DEALDB1,ACCESS=(HDAM,OSAM), RMNAME=(DFSHDC40,1,5,200) DATASET DD1=DFSDLR SEGM NAME=DEALER,PARENT=0,BYTES=61 FIELD NAME=(DLRNO,SEQ,U),BYTES=4,START=1,TYPE=C FIELD NAME=DLRNAME,BYTES=30,START=5,TYPE=C SEGM NAME=MODEL,PARENT=DEALER,BYTES=37 FIELD NAME=(MAKE,SEQ,U),BYTES=10,START=1,TYPE=C FIELD NAME=MODEL,BYTES=10,START=11,TYPE=C DBDGEN FINISH END
| | | | | | | | | | | | | | | | | | | | |
X
Figure 32. Physical DBD for Simple Example
PCB1
| | | | |
PCB TYPE=DB,DBDNAME=DEALDB1,PROCOPT=A,KEYLEN=28 SENSEG NAME=DEALER,PARENT=0 SENSEG NAME=MODEL,PARENT=DEALER PSBGEN PSBNAME=AUTPSB1,LANG=ASSEM,CMPAT=YES END
Figure 33. PSB for Simple Example
Note that the PCB is given a name, as required by IMS Java. In this case a label is used, but a PCBNAME= parameter is also acceptable. A simple MVS JCL execution of the DLIModel utility, using this PSB and DBD, is shown in Figure 34.
| | | | | | | | | |
//BPXAUTP6 JOB CLASS=Z,MSGCLASS=E,MSGLEVEL=(1,1) //TEST EXEC DLIMODEL // DSNAME="DSNAME=IMSVS.TEST1.JCL(EXAMPLE1)" //STEP2.SYSTSIN DD * OCOPY INDD(HFSOUT) OUTDD(STDOUTL) OCOPY INDD(HFSERR) OUTDD(STDERRL) /*
| | | | | | | | | |
Figure 34. Minimal MVS JCL stream
The control data set, DSNAME=IMSVS.TEST1.JCL(EXAMPLE1) is shown in Figure 35. Options GenJavaSource=yes PSBds=IMSVS.TEST1.PSBSRC DBDds=IMSVS.TEST1.DBDSRC PSB PSBName=AUTPSB1
| | | | | | | | | |
Figure 35. Control Data Set for Simple Example
The utility processes a single PSB named AUTPSB1 and its DBD, DEALDB1. The utility reads the PSB and DBD from data sets IMSVS.TEST1.PSBSRC and IMSVS.TEST1.DBDSRC. It generates an IMS Java class only for this PSB, since no other output is requested. The name of the generated class is AUTPSB1DatabaseView (the first 7 characters of this name are set from the PSB name) and the class is written to the HFS file, AUTPSB1DatabaseView.java under the current directory. STDOUT is redirected to SYSOUT, but (in the absence of errors)
78
IMS Java User’s Guide
DLIModel Utility Examples | | |
consists of only startup and normal completion messages. The DLIModel Java Report (produced whenever IMS Java classes are generated) is written to the HFS file, AUTPSB1JavaReport.txt.
| | | | | | | | | | | | | | | | | |
The DLIModel Java Report, shown in Figure 36, describes the generated IMS Java metadata class AUTPSB1DatabaseView.
| | | | |
DLIModel Java Report ======================== Class: AUTPSB1DatabaseView
generated for PSB: AUTPSB1
================================================== PCB: PCB1 ================================================== Segment: DEALER Field: DLRNO Type=CHAR Start=1 Length=4 ++ Primary Key Field ++ Field: DLRNAME Type=CHAR Start=5 Length=30 (Search Field) ================================================== Segment: MODEL Field: MAKE Type=CHAR Start=1 Length=10 ++ Primary Key Field ++ Field: MODEL Type=CHAR Start=11 Length=10 (Search Field)
Figure 36. DLIModel Java Report for Simple Example
Notice these things in the DLIModel Java Report: v The class name, AUTPSB1DatabaseView, is based on the IMS PSB name.
| |
v The PCB name, PCB1, is the same as the label in the PSB PCB statement. v The segment names are the same as the names of the DBD SEGM statements.
|
v The field names are the same as the names in the DBD FIELD statements.
| | | |
These names are all derived from the 8-character (maximum) names in the IMS PSB and DBD source members. These are the defaults that are used when no control statements or XMI COBOL copybook files are supplied to specify more developer-friendly names.
| | |
Each field line displays the starting position and length of the field in the segment, and its type. Again, since there are no control statements or XMI COBOL copybook files to specify otherwise, the type of all fields defaults to CHAR.
| | | | | | |
Each field in the example is annotated as either a primary key field, or a search field. Primary key fields are fields that were designated as a SEQ field in the DBD. Search fields are non-SEQ fields from the DBD. Both field types may be used in the WHERE clause of a JDBC statement, but Primary Key Fields generally provide a much faster response. In the example, these are the only field types, since there are no control statements or XMI COBOL copybook files to add additional fields, and no secondary indexes.
| | | |
Example 2. Example With a Logical Relationship Figure 37 on page 80 and Figure 38 on page 80 show two physical DBDs linked by a bidirectional logical relationship.
Chapter 5. DLIModel Utility
79
DLIModel Utility Examples | | | | | | | | | | | | | | | | | | | |
DBD
NAME=EMPDB2,ACCESS=(HDAM,OSAM), RMNAME=(DFSHDC40,1,5,200) DATASET DD1=DFSEMPL SEGM NAME=EMPL,PARENT=0,BYTES=56 LCHILD NAME=(SALESPER,DEALDB2),PAIR=EMPSAL,POINTER=DBLE FIELD NAME=(EMPNO,SEQ,U),BYTES=6,START=1,TYPE=C FIELD NAME=LASTNME,BYTES=25,START=7,TYPE=C FIELD NAME=FIRSTNME,BYTES=25,START=32,TYPE=C SEGM NAME=EMPSAL,PARENT=EMPL,PTR=PAIRED, SOURCE=((SALESPER,DATA,DEALDB2)) FIELD NAME=(DLRNO2,SEQ,U),BYTES=4,START=1,TYPE=C (LPK) SEGM NAME=EMPLINFO,PARENT=EMPL,BYTES=61 FIELD NAME=(STATE,SEQ,M),BYTES=2,START=51,TYPE=C FIELD NAME=ADDRESS,BYTES=61,START=1,TYPE=C FIELD NAME=STREET,BYTES=25,START=1,TYPE=C FIELD NAME=CITY,BYTES=25,START=26,TYPE=C DBDGEN FINISH END
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
X
X
Figure 37. EMPDB2 Physical DBD for Logical Relationship Example
DBD
NAME=DEALDB2,ACCESS=(HDAM,OSAM), X RMNAME=(DFSHDC40,1,5,200) DATASET DD1=DFSDLR SEGM NAME=DEALER,PARENT=0,BYTES=61 FIELD NAME=(DLRNO,SEQ,U),BYTES=4,START=1,TYPE=C FIELD NAME=DLRNAME,BYTES=30,START=5,TYPE=C FIELD NAME=CITY,BYTES=10,START=35,TYPE=C SEGM NAME=MODEL,PARENT=DEALER,BYTES=37 FIELD NAME=(MODKEY,SEQ,U),BYTES=24,START=3, X TYPE=C FIELD NAME=MODTYPE,BYTES=2,START=1,TYPE=C FIELD NAME=MAKE,BYTES=10,START=3,TYPE=C FIELD NAME=MODEL,BYTES=10,START=13,TYPE=C FIELD NAME=YEAR,BYTES=4,START=23,TYPE=C FIELD NAME=MSRP,BYTES=5,START=27,TYPE=P SEGM NAME=ORDER,PARENT=MODEL,BYTES=74 FIELD NAME=(ORDNBR,SEQ,U),BYTES=6,START=1,TYPE=C FIELD NAME=LASTNME,BYTES=25,START=7,TYPE=C FIELD NAME=FIRSTNME,BYTES=25,START=32,TYPE=C FIELD NAME=DATE,BYTES=10,START=57,TYPE=C LCHILD NAME=(SINDXA,SINDEX2),POINTER=INDX XDFLD NAME=XFLD2,SRCH=(LASTNME,FIRSTNME,ORDNBR), X DDATA=DATE SEGM NAME=SALESPER,PARENT=((DEALER,),(EMPL,PHYSICAL,EMPDB2)),X BYTES=6, X POINTER=(LPARNT,LTWINBWD,TWINBWD), X RULES=(VVV) FIELD NAME=(EMPNO,SEQ,U),BYTES=6,START=1,TYPE=C (LPK) SEGM NAME=SALESINF,PARENT=SALESPER,BYTES=15 FIELD NAME=QUOTA,BYTES=5,START=1,TYPE=C FIELD NAME=SALESYTD,BYTES=5,START=6,TYPE=C FIELD NAME=COMSSION,BYTES=5,START=11,TYPE=C DBDGEN FINISH END
| | | | |
Figure 38. DEALDB2 Physical DBD for Logical Relationship Example
In these two physical DBDs, note that segment, EMPL in EMPDB2 is a logical parent, and it is pointed to by physical logical child, SALESPER in DEALDB2. The
80
IMS Java User’s Guide
DLIModel Utility Examples | | | |
relationship is bidirectional with virtual pairing, and the sequence of the logical child chain is defined through the key field, DLRNO2 in the virtual logical child, EMPSAL in EMPDB2 -- that is actually the destination parent concatenated key from DEALER in DEALDB2.
| | | | | | | | | | | | | | | | | | |
Figure 39 shows a logical DBD based on these two physical DBDs. The logical DBD is rooted in the EMPDB2 physical DBD, and crosses the logical relationship to the DEALDB2 DBD via EMPSAL and DEALER to include the SALESINF segment from the DEALDB2 database. The EMPSAL and DEALER segments form a concatenated segment, with data from both physical segments present in the I/O area.
| | | | | | | | | | | | | | | | | | | | | | | | | | | |
DBD NAME=EMPLDB2,ACCESS=LOGICAL DATASET LOGICAL SEGM NAME=EMPL,PARENT=0,SOURCE=((EMPL,,EMPDB2)) SEGM NAME=DEALER,PARENT=EMPL, SOURCE=((EMPSAL,DATA,EMPDB2),(DEALER,DATA,DEALDB2)) SEGM NAME=SALESINF,PARENT=DEALER, SOURCE=((SALESINF,,DEALDB2)) SEGM NAME=EMPLINFO,PARENT=EMPL, SOURCE=((EMPLINFO,,EMPDB2)) DBDGEN FINISH END
X X X
Figure 39. Logical DBD for Logical Relationship Example
Figure 40 shows a PSB, containing a single PCB that references this logical DBD. Note that field-level sensitivity is used in the logical segment, SALESINF. Only two of the three fields in that segment are visible. Also, in this example, the field lengths and start positions are specified so that there is an empty single byte between the two fields. PCB1
PCB TYPE=DB,DBDNAME=EMPLDB2,PROCOPT=A,KEYLEN=14 SENSEG NAME=EMPL,PARENT=0 SENSEG NAME=DEALER,PARENT=EMPL SENSEG NAME=SALESINF,PARENT=DEALER SENFLD NAME=QUOTA,START=1 SENFLD NAME=SALESYTD,START=7 SENSEG NAME=EMPLINFO,PARENT=EMPL PSBGEN PSBNAME=AUTPSB2,LANG=ASSEM,CMPAT=YES END
Figure 40. PSB with Field-Level Sensitivity for Logical Relationship Example
The JCL stream to execute the utility is similar to that presented in Figure 34 on page 78 of the previous Example 1. The minimal control data set presented in Example 1 could also work for this example. However, the control data set IMSVS.TEST1.JCL(EXAMPLE2) shown in Figure 41 on page 82 makes use of a few more control statements for purposes of illustration.
Chapter 5. DLIModel Utility
81
DLIModel Utility Examples Options PSBds=IMSVS.TEST1.PSBSRC DBDds=IMSVS.TEST1.DBDSRC GenJavaSource=yes Package=example2 GenXMI=yes GenTrace=yes PSB PSBName=AUTPSB2 JavaName=EmployeeView
| | | | | | | | | | | | | | | |
Figure 41. Control Data Set for Logical Relationship Example
The utility processes AUTPSB2, and the DBDs, DEALDB2 and EMPDB2. As already discussed, it reads the PSB and DBD from data sets, IMSVS.TEST1.PSBSRC and IMSVS.TEST1.DBDSRC. The JavaName parameter in the PSB statement sets the name of the generated class, and also determines the names of some of other output files. The utility generates an IMS Java class named, EmployeeView, and writes it to the HFS file, EmployeeView.java. A package statement is included in the class source to specify that the class is part of the package, example2.
| | | | |
An XMI stream describing the data view of AUTPSB5 and its databases is generated and written to the file, xmiOutput.xmi. A trace of the execution is written to the file, dlimodeltrace. The DLIModel Java Report is written to the file, EmployeeViewJavaReport.txt. Since no paths are specified for these outputs, they are all written to the default directory in the HFS file system.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Figure 42 shows the DLIModel Java Report from this execution. It matches the generated IMS Java metadata class (not shown). DLIModel Java Report ======================== Class: EmployeeView in package: example2
generated for PSB: AUTPSB2
================================================== PCB: PCB1 ================================================== Segment: EMPL Field: EMPNO Type=CHAR Start=1 Length=6 ++ Primary Key Field ++ Field: LASTNME Type=CHAR Start=7 Length=25 (Search Field) Field: FIRSTNME Type=CHAR Start=32 Length=25 (Search Field) ================================================== Segment: DEALER Field: DLRNO2 Type=CHAR Start=1 Length=4 ++ Primary Key Field ++ Field: DLRNO Type=CHAR Start=11 Length=4 (Search Field) Field: DLRNAME Type=CHAR Start=15 Length=30 (Search Field) Field: CITY Type=CHAR Start=45 Length=10 (Search Field) ================================================== Segment: SALESINF Field: QUOTA Type=CHAR Start=1 Length=5 (Search Field) Field: SALESYTD Type=CHAR Start=7 Length=5 (Search Field) ================================================== Segment: EMPLINFO Field: STATE Type=CHAR Start=51 Length=2 ++ Primary Key Field ++ Field: ADDRESS Type=CHAR Start=1 Length=61 (Search Field) Field: STREET Type=CHAR Start=1 Length=25 (Search Field) Field: CITY Type=CHAR Start=26 Length=25 (Search Field)
| | | | | | |
Figure 42. DLIModel Java Report for Logical Relationship Example
There are three significant differences in this report as opposed to the preceding simple report shown in Figure 36 on page 79. v First, note that the layout of the DEALER segment reflects the fact that it is a concatenated segment. The first field, DLRNO2, is the destination parent
82
IMS Java User’s Guide
DLIModel Utility Examples | | | | | |
concatenated key associated with the virtual logical child, EMPSAL. Since the logical relationship is being crossed by way of this virtual logical child, its SEQ field, DLRNO2, becomes the key field of the concatenated segment. There are no other fields in the EMPSAL segment, but if there had been, they would have followed the DLRNO2 field in the report. The fields DLRNO, DLRNAME and CITY, are all fields from the destination parent, DEALER, in DEALDB2.
| | | | | | | | | |
v Second, note that the SALESINF segment has two fields, QUOTA and SALEYTD, reflecting the sensitive fields defined in the PSB. Neither is a key field, since the SALESINF segment does not have a defined sequence field in the DBD. v Finally, the EMPLINFO segment illustrates field redefinition in the DBD. The segment primary key field, STATE, appears first, as it does in the DBD. The second field listed, ADDRESS, redefines STREET and CITY, and the key field, STATE. This is indicated by the lengths and starting positions of the fields. IMS Java, the generated metadata class, and the report accommodate any redefinitions present in the FIELD definitions of the IMS DBD.
|
Example 3. Example With a Secondary Index
|
Example 3 uses the same physical DBDs as Example 2.
| | | | | | |
Note that the segment ORDER in DEALDB2 has an XDFLD statement that defines a secondary index search field, XDFLD2, and that it has an LCHILD statement that references the secondary index database, SINDEX2 (as shown in the following fragment).
| | |
The SRCH fields and the DDATA field named in the XDFLD statement all refer to fields in the ORDER segment itself, so in this example the source segment is the same as the target segment. However, this is not required by IMS Java.
| | | | | | | | | | |
The corresponding secondary index database is shown in Figure 43.
| | | | | |
LCHILD XDFLD
NAME=(SINDXA,SINDEX2),POINTER=INDX NAME=XFLD2,SRCH=(LASTNME,FIRSTNME,ORDNBR), DDATA=DATE
DBD NAME=SINDEX2,ACCESS=(INDEX,VSAM) DATASET DD1=SINDX2P SEGM NAME=SINDXA,PARENT=0,BYTES=66 FIELD NAME=(XFLDA,SEQ,U),BYTES=56,START=1,TYPE=C FIELD NAME=DATE,BYTES=10,START=57,TYPE=C LCHILD NAME=(ORDER,DEALDB2),INDEX=XFLD2 DBDGEN FINISH END
X
SEARCH DUP DATA
Figure 43. DBD for Secondary Index Example
The logical database used by this example, Figure 44 on page 84 is based on DEALDB2, and does not cross any logical relationships.
Chapter 5. DLIModel Utility
83
DLIModel Utility Examples DBD NAME=DEALLDB2,ACCESS=LOGICAL DATASET LOGICAL SEGM NAME=DEALER,PARENT=0,SOURCE=((DEALER,,DEALDB2)) SEGM NAME=MODEL,PARENT=DEALER,SOURCE=((MODEL,,DEALDB2)) SEGM NAME=ORDER,PARENT=MODEL,SOURCE=((ORDER,,DEALDB2)) DBDGEN FINISH END
| | | | | | | | | | | | | | | | | | | | |
Figure 44. Logical DBD for Secondary Index Example
The PSB is shown in Figure 45. The PROCSEQ= parameter in the PCB macro specifies a secondary processing sequence using the SINDEX2 secondary index. PCB1
| | | | | | |
PCB TYPE=DB,DBDNAME=DEALLDB2,PROCOPT=GR,KEYLEN=100, PROCSEQ=SINDEX2 SENSEG NAME=ORDER,PARENT=0 SENSEG NAME=MODEL,PARENT=ORDER SENSEG NAME=DEALER,PARENT=MODEL PSBGEN PSBNAME=AUTPSB3,LANG=ASSEM,CMPAT=YES END
X
Figure 45. PSB for Secondary Index Example
This example is intended to be run from the USS prompt, instead of via JCL, as the previous examples were. A hypothetical command line is shown in Figure 46. > java com.ibm.ims.metagen.dlimodel ./ctlfiles/ctl1
| | | | | | | | | | |
Figure 46. MVS USS Command for Secondary Index Example
The control file, ./ctlfiles/ctl1 is shown in Figure 47. Options PSBds=IMSVS.TEST1.PSBSRC DBDds=IMSVS.TEST1.DBDSRC GenJavaSource=yes Package=example3 GenXMI=yes GenTrace=yes PSB PSBName=AUTPSB3 JavaName=OrderView PCB PCBName=PCB1 JavaName=OrdersByName
| | | | |
Figure 47. Control Data Set for Secondary Index Example
In this control data set, a PCB control statement overrides the label in the IMS PCB statement (in the PSB shown in Figure 46) to a more descriptive name. The DLIModel utility generates the DLIModel Java Report in Figure 48 on page 85, together with a matching metadata class (not shown here).
| | |
84
IMS Java User’s Guide
DLIModel Utility Examples | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
DLIModel Java Report ======================== Class: OrderView in package: example3
generated for PSB: AUTPSB3
================================================== PCB: OrdersByName ================================================== Segment: ORDER Field: ORDNBR Type=CHAR Start=1 Length=6 (Search Field) Field: LASTNME Type=CHAR Start=7 Length=25 (Search Field) Field: FIRSTNME Type=CHAR Start=32 Length=25 (Search Field) Field: DATE Type=CHAR Start=57 Length=10 (Search Field) Field: XFLD2 Length=56 ++ Secondary Key Field ++ Component search fields: LASTNME. Length=25. Type=CHAR FIRSTNME. Length=25. Type=CHAR ORDNBR. Length=6. Type=CHAR ================================================== Segment: MODEL Field: MODKEY Type=CHAR Start=3 Length=24 ++ Primary Key Field ++ Field: MODTYPE Type=CHAR Start=1 Length=2 (Search Field) Field: MAKE Type=CHAR Start=3 Length=10 (Search Field) Field: MODEL Type=CHAR Start=13 Length=10 (Search Field) Field: YEAR Type=CHAR Start=23 Length=4 (Search Field) Field: MSRP Type=CHAR Start=27 Length=5 (Search Field) ================================================== Segment: DEALER Field: DLRNO Type=CHAR Start=1 Length=4 ++ Primary Key Field Field: DLRNAME Type=CHAR Start=5 Length=30 (Search Field) Field: CITY Type=CHAR Start=35 Length=10 (Search Field)
Figure 48. DLIModel Java Report for Secondary Index Example
The difference between this Java Report and preceding examples is the presence of the secondary index in the ORDER segment. Note that the ORDER segment no longer has a primary key field, but instead has a field, XDFLD2, annotated as a ++Secondary Key Field++. This field can be used in the WHERE clause of a JDBC call and will function as a primary key field, providing fast response to queries. However, it is a virtual field and it cannot be retrieved from a result set by the application.
| | | | |
In this example, where source and target segments are the same, the component search fields are also present in the ORDER segment, and so they could be retrieved as individual fields. In general, however, these fields may not be defined in the target segment, and so it would not be possible to retrieve them as individual fields.
| | | | | | |
Note also that the component search fields of the secondary index field are listed in the report under the index field description. This information is intended to help the application developer construct suitable search strings for WHERE clauses that use the index field. In this example, since the source and target segments are the same, this information is readily available from the ORDER segment definition itself. However, in general these source fields may not be defined in the target segment, and may not even be present in the Java Report.
| | | | |
Example 4. Example with Multiple Control Statements This example uses the physical database and PSB shown in Figure 49 on page 86 and Figure 50 on page 86 to illustrate the use of control statements to define additional fields and additional name and data type information. It is the same example that is used in Chapter 3, “Accessing an IMS Database” on page 23 to Chapter 5. DLIModel Utility
85
DLIModel Utility Examples describe how to access IMS databases from Java applications using JDBC. This example also illustrates how control statements might be split across more than one file.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
DBD NAME=DEALERDB,ACCESS=(HDAM,OSAM),RMNAME=(DFSHDC40.1.10) SEGM NAME=DEALER,PARENT=0,BYTES=94 FIELD NAME=(DLRNO,SEQ,U),BYTES=4,START=1,TYPE=C FIELD NAME=DLRNAME,BYTES=30,START=5,TYPE=C SEGM NAME=MODEL,PARENT=DEALER,BYTES=43 FIELD NAME=(MODTYPE,SEQ,U),BYTES=2,START=1,TYPE=C FIELD NAME=MAKE,BYTES=10,START=3,TYPE=C FIELD NAME=MODEL,BYTES=10,START=13,TYPE=C FIELD NAME=YEAR,BYTES=4,START=23,TYPE=C FIELD NAME=MSRP,BYTES=5,START=27,TYPE=P SEGM NAME=ORDER,PARENT=MODEL,BYTES=127 FIELD NAME=(ORDNBR,SEQ,U),BYTES=6,START=1,TYPE=C FIELD NAME=LASTNME,BYTES=25,START=50,TYPE=C FIELD NAME=FIRSTNME,BYTES=25,START=75,TYPE=C SEGM NAME=SALES,PARENT=MODEL,BYTES=113 FIELD NAME=(SALDATE,SEQ,U),BYTES=8,START=1,TYPE=C FIELD NAME=LASTNME,BYTES=25,START=9,TYPE=C FIELD NAME=FIRSTNME,BYTES=25,START=34,TYPE=C FIELD NAME=STKVIN,BYTES=20,START=94,TYPE=C SEGM NAME=STOCK,PARENT=MODEL,BYTES=62 FIELD NAME=(STKVIN,SEQ,U),BYTES=20,START=1,TYPE=C FIELD NAME=COLOR,BYTES=10,START=37,TYPE=C FIELD NAME=PRICE,BYTES=5,START=47,TYPE=C FIELD NAME=LOT,BYTES=10,START=53,TYPE=C DBDGEN FINISH END
| | | | | | | | | | | |
Figure 49. Physical DBD for Multiple Control Statements Example
DLR_PCB1 PCB SENSEG SENSEG SENSEG SENSEG SENSEG PSBGEN END
| | | | | |
TYPE=DB,DBDNAME=DEALERDB,PROCOPT=GO,KEYLEN=42 NAME=DEALER,PARENT=0 NAME=MODEL,PARENT=DEALER NAME=ORDER,PARENT=MODEL NAME=SALES,PARENT=MODEL NAME=STOCK,PARENT=MODEL PSBNAME=DLR_PSB,MAXQ=200
Figure 50. PSB for Multiple Control Statements Example
The example is executed from the MVS USS prompt, as shown in Figure 51. > java com.ibm.ims.metagen.dlimodel ./ctlfiles/ctl4
| | | | |
Figure 51. MVS USS Command for Control Statements Example
The top-level control statement file, ctl4, is shown in Figure 52 on page 87.
86
IMS Java User’s Guide
DLIModel Utility Examples | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
OPTIONS
PSBds=IMSVS.TEST1.PSBSRC DBDds=IMSVS.TEST1.DBDSRC GenJavaSource=YES gentrace=yes outpath=gen Package=com.ibm.ims.tooling
PSB psbName=DLR_PSB JavaName=DealerDatabaseView PCB PCBName=DLR_PCB1 JavaName=DealershipDB Include Dataset=tests.samp.ctl/cntrstmt2
Figure 52. Top-Level Control Data Set for Multiple Control Statements Example
This control file establishes the options for the execution, as in previous examples, and directs the outputs (generated classes, java report, and trace) to a specified directory (outpath=gen). It also names the PSB to be processed, assigns a Java name for the generated class for this PSB, and provides a Java name for a PCB in that PSB. Unlike previous examples, this example includes a second-level control statement file, called cntrstmt2, which is shown in Figure 53 on page 88. This control file provides details of additional fields in the segments of the database referenced from DLR_PCB1, and additional information about existing fields in that database. Note two facts about this second control statement file: v The information it contains is only necessary because there are additional facts about the segments in this database that are needed by this (hypothetical) Java application. If your DBD names all the fields that are used by your application, and if all the fields can be treated as CHAR data type, and if your application can use the standard 8-character names, then you would not need to supply SEGM or Field control statements. v The Segment and Field control statements need only be split off into a second file if it is convenient to do so, perhaps because this additional segment information needs to be shared by other applications. In such cases you might group all field information for a whole database (as is shown in Figure 53 on page 88) or for each segment into its own file. If this is not advantageous for your data, it is equally acceptable to place all control statements in a single, top-level file.
|
Chapter 5. DLIModel Utility
87
DLIModel Utility Examples | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
SEGM DBDName=DEALERDB SegmentName=DEALER JavaName=DEALERXX FIELD Name=DLRNO Start=1 Bytes=4 JavaType=CHAR FIELD Start=5 Bytes=30 JavaType=CHAR FIELD Start=35 Bytes=50 JavaType=CHAR FIELD Start=85 Bytes=10 JavaType=PACKEDDECIMAL TypeQualifier=S9(18)
JavaName=DealerNumber JavaName=DealerName JavaName=DealerAddress JavaName=YTDSales
SEGM DBDName=DEALERDB SegmentName=MODEL JavaName=MODELXX FIELD Name=MODTYPE Start=1 Bytes=2 JavaType=CHAR JavaName=ModelTypeCode FIELD Name=MAKE Start=3 Bytes=10 JavaType=CHAR JavaName=CarMake FIELD Name=MODEL Start=13 Bytes=10 JavaType=CHAR JavaName=CarModel FIELD Name=YEAR Start=23 Bytes=4 JavaType=CHAR JavaName=CarYear FIELD Name=MSRP Start=27 Bytes=5 JavaType=CHAR JavaName=Price FIELD Start=32 Bytes=4 JavaType=CHAR JavaName=EPACityMilage FIELD Start=36 Bytes=4 JavaType=CHAR JavaName=EPAHighwayMilage FIELD Start=40 Bytes=4 JavaType=CHAR JavaName=Horsepower SEGM DBDName=DEALERDB FIELD Name=ORDNBR FIELD FIELD FIELD FIELD Name=LASTNME FIELD Name=FIRSTNME FIELD FIELD
SegmentName=ORDER JavaName=ORDERXX Start=1 Bytes=6 JavaType=CHAR JavaName=OrderNumber Start=7 Bytes=30 JavaType=CHAR JavaName=Options Start=37 Bytes=5 JavaType=ZONEDDECIMAL TypeQualifier=99999 JavaName=Price Start=42 Bytes=8 JavaType=CHAR JavaName=OrderDate Start=50 Bytes=25 JavaType=CHAR JavaName=PurchaserLastName Start=75 Bytes=25 JavaType=CHAR JavaName=PurchaserFirstName Start=100 Bytes=8 JavaType=CHAR JavaName=SerialNo Start=120 Bytes=8 JavaType=CHAR JavaName=DeliverDate
SEGM DBDName=DEALERDB FIELD Name=SALDATE FIELD Name=LASTNME FIELD Name=FIRSTNME FIELD FIELD FIELD Name=STKVIN
SegmentName=SALES Start=1 Bytes=8 Start=9 Bytes=25 Start=34 Bytes=25 Start=59 Bytes=25 Start=84 Bytes=10 Start=94 Bytes=20
JavaName=SALESXX JavaType=CHAR JavaName=DateSold JavaType=CHAR JavaName=PurchaserLastName JavaType=CHAR JavaName=PurchasetFirstName JavaType=CHAR JavaName=PurchaserAddress JavaType=CHAR JavaName=SoldBy JavaType=CHAR JavaName=StockVINumber
SEGM DBDName=DEALERDB SegmentName=STOCK JavaName=STOCKXX FIELD Name=STKVIN Start=1 Bytes=20 JavaType=CHAR FIELD Start=21 Bytes=8 JavaType=CHAR FIELD Start=29 Bytes=8 JavaType=CHAR FIELD Name=COLOR Start=37 Bytes=10 JavaType=CHAR FIELD Name=PRICE Start=47 Bytes=5 JavaType=ZONEDDECIMAL TypeQualifier=99999 FIELD Name=LOT Start=53 Bytes=10 JavaType=CHAR
JavaName=StockVINumber JavaName=DateIn JavaName=DateOut JavaName=Color JavaName=Price JavaName=Lot
| | Figure 53. Second-Level Control Data Set for Multiple Control Statements Example | Under the SEGM statement for DEALER, the first Field statement identifies an | existing field, DLRNO, by both its DBD name and its start position and length. | These facts will be checked for consistency against the DBD. If the field is identified | correctly, then it is assigned a Java name, DealerNumber, and a data type, CHAR | (which is the default, and therefore not necessary to specify). | | | | | |
The second Field statement identifies an existing field by only its start position and length. If such a field exists, it is assigned the Java name, DealerName. This abbreviated method of identifying the field achieves the same result, but is not quite so safe because no 8-character name check is carried out. The data type for DealerName default is CHAR.
| | | |
The third Field statement under the DEALER SEGM statement defines a new field -- a field that is physically present in the segment, but is not described by a FIELD macro in the DBD. It specifies the start position and length of this field, assigns it a Java name of DealerAddress, and a type of CHAR.
88
IMS Java User’s Guide
DLIModel Utility Examples | | |
The fourth Field statement defines another new field, YTDSales, of type PACKEDDECIMAL. This data type requires a type qualifier that defines the field format, and in this example, a qualifier of S9(18) is supplied.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
The remainder of the control statements describe information for the other segments and fields in the DBD in a similar manner. When DLIModel is executed, it generates the DLIModel Java Report in Figure 23, together with a matching metadata class (not shown here). DLIModel Java Report ======================== Class: DealerDatabaseView
generated for PSB: DLR_PSB
================================================== PCB: DealershipDB ================================================== Segment: DEALERxx Field: DealerNumber Type=CHAR Start=1 Length=4 ++ Primary Key Field ++ Field: DealerName Type=CHAR Start=5 Length=30 (Search Field) Field: DealerAddress Type=CHAR Start=35 Length=50 Field: YTDSales Type=PACKEDDECIMAL Type Qualifier=S9(18) Start=85 Length=10 ================================================== Segment: MODELXX Field: ModelTypeCode Type=CHAR Start=1 Length=2 ++ Primary Key Field ++ Field: CarMake Type=CHAR Start=3 Length=10 (Search Field) Field: CarModel Type=CHAR Start=13 Length=10 (Search Field) Field: CarYear Type=CHAR Start=23 Length=4 (Search Field) Field: Price Type=CHAR Start=27 Length=5 (Search Field) Field: EPACityMilage Type=CHAR Start=32 Length=4 Field: EPAHighwayMilage Type=CHAR Start=36 Length=4 Field: Horsepower Type=CHAR Start=40 Length=4 ================================================== Segment: ORDERXX Field: OrderNumber Type=CHAR Start=1 Length=6 ++ Primary Key Field ++ Field: PurchaserLastName Type=CHAR Start=50 Length=25 (Search Field) Field: PurchaserFirstName Type=CHAR Start=75 Length=25 (Search Field) Field: Options Type=CHAR Start=7 Length=30 Field: Price Type=ZONEDDECIMAL Type Qualifier=99999 Start=37 Length=5 Field: OrderDate Type=CHAR Start=42 Length=8 Field: SerialNo Type=CHAR Start=100 Length=8 Field: DeliverDate Type=CHAR Start=120 Length=8 ================================================== Segment: SALESXX Field: DateSold Type=CHAR Start=1 Length=8 ++ Primary Key Field ++ Field: PurchaserLastName Type=CHAR Start=9 Length=25 (Search Field) Field: PurchasetFirstName Type=CHAR Start=34 Length=25 (Search Field) Field: StockVINumber Type=CHAR Start=94 Length=20 (Search Field) Field: PurchaserAddress Type=CHAR Start=59 Length=25 Field: SoldBy Type=CHAR Start=84 Length=10 ================================================== Segment: STOCKXX Field: StockVINumber Type=CHAR Start=1 Length=20 Field: Color Type=CHAR Start=37 Length=10 Field: Price Type=CHAR Start=47 Length=5 Field: Lot Type=CHAR Start=53 Length=10 Field: DateIn Type=CHAR Start=21 Length=8 Field: DateOut Type=CHAR Start=29 Length=8
++ Primary (Search (Search (Search
Key Field ++ Field) Field) Field)
| | Figure 54. DLIModel Java Report for Multiple Control Statements Example | | In this DLIModel Java Report, the names of segments and fields are the Java | names supplied in the control statements. The eight-character IMS names do not | appear because the Java developer does not need to know these names. Chapter 5. DLIModel Utility
89
DLIModel Utility Examples
90
IMS Java User’s Guide
Chapter 6. Problem Determination This chapter contains information on debugging your IMS Java programs and determining the source of problems within your IMS Java programs. In this Chapter: v “Exceptions” v “Sync Point Failure” on page 93 v “GU Message Failure” on page 93 v “Abends” on page 93 v “DLIModel Messages” on page 94 v “IMSTrace” on page 96
Exceptions Exceptions are thrown as a result of non-blank status codes and non-zero return codes (in cases when there were no PCBs to deliver status codes) from IMS DL/I calls. Even though an exception is thrown by JavaToDLI for every non-blank status code, some of these exceptions are caught by the application or database packages and converted to return values.
How Exceptions Map to DL/I Status Codes IMSException extends java.lang.Exception. DLIException extends IMSException. Exceptions of this type include all errors that occur within the IMS Java library and are not a result of any call to IMS. You can use the following methods to extract information from an IMSException: getAIB Returns the IMS AIB from the DL/I call that caused the exception. IMS AIB is null for DLIException. The methods on the AIB can be called to return other information at the time of the failure, including the resource or PCB name and the PCB itself. | | |
getStatusCode Returns the IMS status code from the DL/I call that caused the exception. This method works with the JavaToDLI set of constants. The status code is zero (0) for a DLIException. getFunction Returns the IMS function from the DL/I call that caused the exception. Function is zero (0) for a DLIException.
| | | | |
The database access methods of DLIConnection in Figure 55 on page 92 return false if they receive GB (no more such segments or segment not found) or GE (no such segment or end of database) status codes and they are consumed by DLIConnection.
© Copyright IBM Corp. 2000, 2002
91
Exceptions DLIConnection.getUniqueSegment DLIConnection.getNextSegment DLIConnection.getUniqueRecord DLIConnection.getNextRecord DLIConnection.getNextSegmentInParent
Figure 55. Database access methods of DLIConnection
The IMSMessageQueue.getUniqueMessage method returns false if it receives a QC (no more messages) status code. The IMSMessageQueue.getNextMessage method returns false if it receives a QD (no more segments [for multi-segment messages]) status code. These exceptions are consumed by IMSMessageQueue. Figure 56 shows an example of extracting information from an IMSException: try { DealerDatabaseView dealerView = new DealerDatabaseView(); DLIConnection connection = DLIConnection.createInstance(dealerView); connection.getUniqueSegment(dealerSegment, dealerSSAList); } catch (IMSException e ) { short statusCode = e.getStatusCode(); String failingFunction = e.getFunction(); }
Figure 56. IMSException Sample
Related Reading: For more information on DL/I Status Codes see IMS Version 7 Application Programming: Database Managerand IMS Version 7 Application Programming: Transaction Manager.
SQLExceptions SQLException is thrown to indicate that an error has occurred either in the Java address space or during database processing. Each SQLException provides the following information: v A string describing the error. – This string is available through the use of the getMessage() method. v An “SQLstate” string that follows XOPEN SQLstate conventions.
|
– The values of the SQLstate string are described in the XOPEN SQL specification. v A link to the next SQL exception if more than one was generated . – The next exception is used as a source of additional error information.
92
IMS Java User’s Guide
Sync Point Failure
Sync Point Failure If you receive an SY DL/I PCB status code, your IMS Java application SYNC request call has failed. Table 6 describes the failure. Table 6. Status Code, Reason, and Return Code DL/I Return/ Reason Code 0108/ 056C
PCB Status Code SY
System Service Call IMS Java sync
Category
5
Description
Internal error during sync point processing for an IMS Java application. Sync point failure. AIBERRXT contains the SYNC return code.
A call to the sync point processor (DFSTMS00) returned a non-zero return code. Contact your IMS system programmer. |
GU Message Failure
| | |
If you receive a CR DL/I PCB status code, your IMS Java application GU message request call has failed. Table 7 describes the failure. Correct your application to issue a Java commit prior to issuing your next GU message call.
|
Table 7. Status Code, Reason, and Return Code
| | | |
AIB Return/ Reason Code
| | |
0104/ 0300
PCB Status Code CR
System Service Call IMS Java GU Message
Category
4
Description
Application error during GU message processing for an IMS Java application.
Abends An abend is the abnormal ending of a program or application. When an abend error condition occurs, an abend macro is issued either at the point of error detection or by branching to a routine that issues the abend macro. There are also pseudoabends in which the module that detects the error condition does not issue the abend macro. Instead, it passes control back to the IMS call analyzer module, DFSDLA00, which writes the contents of important control blocks to the system log and indicates a dependent-region abend. Following are the abends that you might encounter as a result of errors while running IMS Java applications.
ABENDU0118 - Commit Failure | | |
This abend is issued if your IMS Java application attempts to terminate without calling IMSTransaction.commit. An explicit commit is required for each IMS Java application before it can terminate normally. Related Reading: For more information on ABENDU0118, see IMS Version 7 Failure Analysis Structure Tables (FAST) for Dump Analysis and IMS Version 7 Messages and Codes, Volume 1.
Chapter 6. Problem Determination
93
Sync Point Failure
ABENDU0475 - Batch Run Failure This abend is issued if your IMS Java application attempts to run as an IMS Batch job. IMS batch does not currently support IMS Java applications. Related Reading: For more information on ABENDU0475, see IMS Version 7 Failure Analysis Structure Tables (FAST) for Dump Analysis, and IMS Version 7 Messages and Codes, Volume 2.
Processing Dumps You might be asked to help interpret a dump for diagnostic purposes. Related Reading: v For more information on dump processing, see IMS Version 7 Installation Volume 2: System Definition and Tailoring and IMS Version 7 Utilities Reference: Database and Transaction Manager. v For more information on dump analysis, see IMS Version 7 Failure Analysis Structure Tables (FAST) for Dump Analysis and the IMS Version 7 Diagnosis Guide and Reference. |
DLIModel Messages
|
This section describes the messages that are issued by the DLIModel utility.
| |
The DLIModel utility message number severity suffixes are as follows unless otherwise indicated:
|
E
Unrecoverable error
|
W
Warning
|
I
Informational message
| | DHM0001 |
System Error: text (class/method) (DHM0001E)
| | |
Explanation: This message describes a probable error in the DLIModel utility during the import of a PSB or DBD.
|
text
| | |
(class/method) -describes the location; class or method name, in DLIModel at which the error was detected
| |
(DHM00001E) -the message reference number
| | | | | | |
Programmer Response: Call IBM for service. Have these things available:
| | |
Problem Determination: You may be asked to rerun DLIModel with the option parameter, Trace=yes set in order to aid in the problem determination.
v
-describes the problem
the content of this message
v the input PSBs and all related DBDs v control statement data set or file v the JCL or USS command that you used to execute the utility
94
IMS Java User’s Guide
| | DHM0002 through DHM0199 text (class/method) (DHM0xxxE) | | | | |
Explanation: Messages in this range describe problems in the input data that prevent the utility from continuing during the import of a PSB or DBD. As a result, the utility terminates.
| text
-describes the problem
| (class/method) -describes the location; class or method name, | in DLIModel at which the error was detected | | (DHM0xxxE) -the message reference number | | | | | | | | | |
xxx
the last three digits of the message number, in the range: 2 through 199
Programmer Response: Typically, this error is the result of incorrect or inconsistent PSB or DBD source data. It is strongly recommended that PSBs and DBDs are compiled, an ACBGEN is performed, and all errors are corrected before running the DLIModel utility. If these tasks are not done, there is no guarantee that the DLIModel utility will detect all potential errors in the PSB
DLIModel Messages | or DBD source, so the resulting output might be | incomplete or incorrect. | | | | | | | | |
If the PSBs and the DBDs have been validated (through PSBGEN, DBDGEN, and ACBGEN) but the problem persists, call IBM for service. Have these things available: v the content of this message v the input PSBs and DBDs v the control statement data set or file v the JCL or USS command that you used to execute the utility
| Problem Determination: You may be asked to rerun | DLIModel with the option parameter, Trace=yes set in | order to aid in the problem determination. | | DHM0200 through DHM0299 | | | | |
text (DHM02xxW)
Explanation: These messages describe warnings of problems with the input data that did not prevent the DLIModel utility from continuing. In most cases part of the input data is ignored in order to circumvent the problem, and this might result in incomplete output.
| text
-describes the problem
| (DHM02xxW) -the message reference number | | | | | | | | | | | | |
xx
the last two digits of the message number, in the range: 0 through 99
Programmer Response: The utility output (for example the IMS Java metadata classes) should be carefully reviewed before use. In some cases the output will be usable after one of these warnings -- for example, a PSB may contain a PCB that references an MSDB type database, which cannot be handled by the utility. The generated IMS Java classes report of the XMI file will omit the MSDB database, that would typically be acceptable for an IMS Java application that used the metadata classes.
| | DHM0500 through DHM0599 text (DHM05xxy) | Explanation: These messages describe standard | actions taken, warnings, and errors that occur during | the processing of the DLIModel control statement file. | text
-describes the problem
| (DHM05xxy) -the message reference number | | |
xx
the last two digits of the message number, in the range: 0 through 99
|
y
one of these severities:
|
I
informational
|
W
warning
|
E
error
| Programmer Response: | Informational messages: Confirm that the action that was performed by | the utility is acceptable. | | Warning messages: These messages describe an error that could | be corrected or ignored by the utility, allowing it | to continue,. Frequently this is done by ignoring | part of one or more control statements. | | | | |
Confirm that the action that was performed by the utility is acceptable by reviewing the message and the generated output. Correct and rerun the utility if necessary.
| Error messages: These messages describe an error that caused | the utility to terminate. Correct the error and | rerun the utility. In some cases, one of these | messages is followed by related messages that | describe a system error, or an error or a | warning regarding input data. | | | DHM0800W through DHM0899W text (DHM008xxE) | Explanation: These messages describe errors that | occur during the export of the IMS Java metadata | classes and the Java report. | text
-describes the problem
| (DHM08xxE) -the message reference number | | |
xx
the last two digits of the message number, in the range: 0 through 99
| | | | | | |
Programmer Response: Message DHM0800E describes problems that are probable system errors. Call IBM for service. Have the following things available: the content of this message, the input PSB and all related DBDs, control statement data set or file, and the JCL or USS command that was used to execute the utility
| | | | | | | | |
Other messages in this range are often caused by incorrect or inconsistent PSB or DBD source data. It is strongly recommended that PSBs and DBDs be compiled, an ACBGEN performed, and all errors corrected before running the DLIModel utility. If these tasks are not done, there is no guarantee that the DLIModel utility will detect all potential errors in the PSB or DBD source, and the export of IMS Java entities may fail, resulting in one of these messages.
| | | | | | |
If the PSBs and the DBDs have been validated (through PSBGEN, DBDGEN, and ACBGEN) but the problem persists, call IBM for service. Have these things available: v the content of this message v the input PSBs and DBDs v the control statement data set or file
Chapter 6. Problem Determination
95
DLIModel Messages | v the JCL or USS command that you used to execute the utility |
| |
DLIModel with the option parameter, Trace=yes set in order to aid in the problem determination.
| Problem Determination: You may be asked to rerun |
IMSTrace With IMSTrace, you can debug your Java applications by tracing, or documenting, the flow of control throughout your application. By setting up tracepoints throughout your applications for output, you can isolate problem areas and, therefore, know where to make adjustments to produce the results you expect. In addition, because IMSTrace supports writing input parameters and results, and the IMS-Java-library-provided routines use this feature, you can verify that correct results occur across method boundaries. IMSTrace is distinct from the DLIModel utility trace. For information on how to set the DLIModel utility trace, see “OPTIONS Statement” on page 68.
Initiating IMSTracing To debug with IMSTrace, you must first turn on the tracing function by setting the IMSTrace.traceOn variable to true. Because tracing does not occur until this variable is set, it is best to do so within a static block of your main application class. Then, you must decide how closely you want to trace the IMS Java library’s flow of control, and how much tracing you want to add to your application code.
| | | | |
You determine the amount of tracing in the IMS Java library by setting the value of IMSTrace.libTraceLevel to one of its predefined values. By default, this value is set to IMSTrace.TRACE_EXCEPTIONS, which traces the construction of IMS-Java-library-provided exceptions. IMSTrace also defines constants for three types of additional tracing. These constants provide successively more tracing from IMSTrace.TRACE_CTOR1 (level one tracing of constructions) to IMSTrace.TRACE_DATA3 (level three tracing of data).
Setting up Tracing for the IMS Java Library Routines | | | | | | | | | | | | |
To turn on the tracing shipped with the IMS Java Library Routines: 1. Turn on the flag enabling tracing (it is turned off by default):
| | |
These steps are best implemented within a static method of your main class, as shown in Figure 57 on page 97:
IMSTrace.traceOn = true;
2. Set the level of tracing for the IMS Java Library Routines. In this example, constructors and the entry and exit of level one methods are traced: IMSTrace.libTraceLevel = IMSTrace.TRACE_METHOD1;
3. Set an output stream (a print stream or a character output writer) as the current trace stream. For example: a. Set the system error stream as the current trace stream: IMSTrace.setOutputStream(System.err);
b. Set a StringWriter (an in-memory buffer) as the current trace stream: StringWriter stringWriter = new StringWriter(); IMSTrace.setOutputWriter(stringWriter);
96
IMS Java User’s Guide
IMSTrace public class IMSAuto extends IMSApplication { static { IMSTrace.traceOn = true; IMSTrace.libTraceLevel = IMSTrace.TRACE_METHOD1; IMSTrace.setOutputStream(System.err); } public static void main(String args[]){ IMSAuto application = new IMSAuto(); application.begin(); } }
Figure 57. Setting a Trace within a Static Method
Adding Trace Statements to Your Application You can add trace statements to your application, similar to those provided by the IMS Java Library, by defining an integer variable that you test prior to writing trace statements. Using a variable other than IMSTrace.libTraceLevel enables you to control the level of tracing in your application independently of the tracing in the IMS Java library. For example, you can turn off the tracing of IMS Java Library routines by setting IMSTrace.libTraceLevel to zero but still trace your application code. Follow these steps to add tracing to your application code: 1. Define an integer variable to contain the trace level for application-provided code: public class IMSAuto extends IMSApplication { public int applicationTraceLevel = IMSTrace.TRACE_CTOR3;
2. Set up IMSTrace to trace methods, parameters, and return values as necessary, as shown in Figure 58: public class IMSAuto extends IMSApplication { public static int applicationTraceLevel=IMSTrace.TRACE_CTOR3; static { IMSTrace.traceOn = true; IMSTrace.libTraceLevel = IMSTrace.TRACE_METHOD1; IMSTrace.setOutputStream(System.err); } public static void main (String args[]) { IMSAuto application = new IMSAuto(); application.begin(); }
Figure 58. Setting Up IMSTrace (Part 1 of 3)
Chapter 6. Problem Determination
97
IMSTrace public void doBegin() throws IMSException { if (IMSAuto.applicationTraceLevel >= IMSTrace.TRACE_METHOD1) IMSTrace.currentTrace().logEntry("IMSAuto.doBegin"); try { //Add code here . . . } finally { if (IMSAuto.applicationTraceLevel >= IMSTrace.TRACE_METHOD1) IMSTrace.currentTrace().logExit("IMSAuto.doBegin"); } } public String method1(String parm1){ if (IMSAuto.applicationTraceLevel >= IMSTrace.TRACE_METHOD2) { IMSTrace.currentTrace().logEntry("IMSAuto.method1"); if (IMSAuto.applicationTraceLevel >= IMSTrace.TRACE_DATA2) IMSTrace.currentTrace().logParm("parm1", parm1); } String result = new String(); try { //Add code here . . . result = "result"; }
Figure 58. Setting Up IMSTrace (Part 2 of 3)
finally { if (IMSAuto.applicationTraceLevel >= IMSTrace.TRACE_METHOD2) IMSTrace.currentTrace().logExit("IMSAuto.method1"); } return result; }
Figure 58. Setting Up IMSTrace (Part 3 of 3)
98
IMS Java User’s Guide
| |
Appendix A. Manually Creating IMS Java Metadata Classes
| |
This appendix describes the procedure for manually creating the metadata classes required for JDBC access to IMS databases.
| |
Note: The recommended method for creating these classes is to use the DLIModel utility, described in Chapter 5, “DLIModel Utility” on page 61.
| | | | | | |
Mapping an IMS Database in Java Classes To map an IMS database in Java classes, you use the segments and fields in the Database Definition (DBD) to create DLIDatabaseView and DLISegment subclasses. The hierarchical database shown in Figure 59 is used as the sample database in the code examples that follow.
Figure 59. Example Database and Segments
| | | | | |
IMS Database Definition (DBD) The Database Definition (DBD) is set up by the database administrator. A DBD defines the segments (″SEGM NAME″) and key fields (″FIELD NAME″) of the database. Figure 60 on page 100 is the DBD for the sample hierarchical database in Figure 59.
Adding Default Values for Fields of a Segment
| | | | |
In certain cases, you might want to assign a default value for a particular Field of a Segment definition. You may want the defaults, for example, when assigning values that may not be set in the application, or for reducing the amount of required application setup for insert segment calls. To assign an initial default value manually modify the constructor for the generated DLIDatabaseView subclass.
| | | |
After the super() and any addDatabase() calls in the generated DLIDatabaseView subclass, a setString(), setInt(), or any setXXX() call can be made to set the default value. This default value remains constant throughout the application and so will exist in all cloned instances of the Segment.
| |
The following example demonstrates how to add a default value of Chris to the PersonalHero Field of the Employee Segment:
© Copyright IBM Corp. 2000, 2002
99
static DLITypeInfo[] PCB1EMPLOYEEArray= { new DLITypeInfo("LastName", DLITypeInfo.CHAR, 1, 25, "LASTNME"), new DLITypeInfo("FirstName", DLITypeInfo.CHAR, 26, 25, "FIRSTNME") new DLITypeInfo("PersonalHero", DLITypeInfo.CHAR, 51, 25, "HERO"), }; static DLISegment PCB1EMPLOYEESegment= new DLISegment ("EmployeeSegment","EMPLOYEE",PCB1EMPLOYEEArray,76);
| | | | | | | | | | | | | | | | | | | | |
//Constructor public EmpPSB1DatabaseView() { super("EMPPSB1", "pcb1", "PCB1", PCB1array); addDatabase("pcb2", "PCB2", PCB2array); // Set Default PCB1EMPLOYEESegment.setString("PersonalHero", "Chris"); } try { // Set Default ... } catch (com.ibm.ims.db.DLIException e) { throw new RuntimeException(e.toString()); }
Mapping the PSB to DLIDatabaseView
| | |
The PSB (Program Status Block) defines a grouping of resources available to an application. Included in the PSB is a DB PCB (Database Program Communication Block) definition for each database that your application can access.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
The DB PCB defines the access rights that your application has to the segments of the database. In particular, a database PCB (PCB Type=DB) defines which segments, and which fields within those segments, your program can access, and the access intent (such as get, insert, replace, delete, or all) and isolation level (such as dirty read) that is used when accessing a database by way of that PCB. DBD NAME=DEALERDB,ACCESS=(HDAM,OSAM),RMNAME=(DFSHDC40.1.10) SEGM NAME=DEALER,PARENT=0,BYTES=94, FIELD NAME=(DLRNO,SEQ,U),BYTES=4,START=1,TYPE=C FIELD NAME=DLRNAME,BYTES=30,START=5,TYPE=C SEGM NAME=MODEL,PARENT=DEALER,BYTES=43 FIELD NAME=(MODTYPE,SEQ,U),BYTES=2,START=1,TYPE=C FIELD NAME=MAKE,BYTES=10,START=3,TYPE=C FIELD NAME=MODEL,BYTES=10,START=13,TYPE=C FIELD NAME=YEAR,BYTES=4,START=23,TYPE=C FIELD NAME=MSRP,BYTES=5,START=27,TYPE=P SEGM NAME=ORDER,PARENT=MODEL,BYTES=127 FIELD NAME=(ORDNBR,SEQ,U),BYTES=6,START=1,TYPE=C FIELD NAME=LASTNME,BYTES=25,START=50,TYPE=C FIELD NAME=FIRSTNME,BYTES=25,START=75,TYPE=C SEGM NAME=SALES,PARENT=MODEL,BYTES=113 FIELD NAME=(SALDATE,SEQ,U),BYTES=8,START=1,TYPE=C FIELD NAME=LASTNME,BYTES=25,START=9,TYPE=C FIELD NAME=FIRSTNME,BYTES=25,START=34,TYPE=C FIELD NAME=STKVIN,BYTES=20,START=94,TYPE=C SEGM NAME=STOCK,PARENT=MODEL,BYTES=62 FIELD NAME=(STKVIN,SEQ,U),BYTES=20,START=1,TYPE=C FIELD NAME=COLOR,BYTES=10,START=37,TYPE=C FIELD NAME=PRICE,BYTES=5,START=47,TYPE=C FIELD NAME=LOT,BYTES=10,START=53,TYPE=C DBDGEN FINISH END
| | |
Figure 60. DBD Sample Definition
100
IMS Java User’s Guide
| | | | | |
You define the information that is needed to connect to one or more databases from within an application with the DLIDatabaseView. In IMS Java, the DLIDatabaseView class contains metadata (information describing the data in the database, such as types and lengths of fields) that describes your application’s view of the databases that it uses. The DLIDatabaseView class includes the PSB name and any PCBs, segments, and fields that are used by the application.
| | | | | | | | | |
The DLIDatabaseView subclass contains information from both the PSB and the DBD, including the following information: v The PSBNAME from the PSBGEN macro of the PSB definition v The PCB names of any PCB macros in the PSB definition v The segments defined for a PCB using the SENSEG macro of the PSB definition. v The fields defined within a segment. These are usually defined only within the DBD, but their use may be restricted by the SENFLD macro in the PSB definition. Figure 61 on page 102 shows the PSB definition for the Dealership application.
| | | | | | | | | | | | | | | | | | |
DLIDatabaseView Example Using information from the PSB shown in Figure 61 on page 102, create a DLIDatabaseView subclass called DealerDatabaseView. The numbers in the following list (for example, 1) are referenced in Figure 61 on page 102. Note the following: v Within the subclass you create an array of DLISegmentInfo objects, one entry for each DLISegment object used by the application. 1 As you will see in “DLISegment Example” on page 103, a DLISegment object defines the fields in a database segment similar to the way an IMSFieldMessage object defines the fields in a message segment. v Each DLISegmentInfo object associates a DLISegment object to its parent. 2 The parent is specified as a zero-based index in the array. Notice that the entry for the Order segment specifies an index of 1, which is the index in the array for the Model segment. v The parent of the root segment, Dealer, is specified by the constant DLIDatabaseView.ROOT to indicate that it has no parent. 3 v The dealer PSB name, DLR_PSB, is passed in the DealerDatabaseView constructor to the super class constructor along with the array of DLISegmentInfo objects. 4
|
Appendix A. Manually Creating IMS Java Metadata Classes
101
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 102
import com.ibm.ims.db.*; import com.ibm.ims.base.*; public class DealerDatabaseView extends DLIDatabaseView { static DLITypeInfo[] dealerInfo = { new DLITypeInfo("DealerNo",DLITypeInfo.CHAR, 1, 4, "DLRNO"), new DLITypeInfo("DealerName",DLITypeInfo.CHAR, 5, 30, "DLRNAME"), new DLITypeInfo("DealerCity",DLITypeInfo.CHAR, 35, 10, "CITY"), new DLITypeInfo("DealerZip",DLITypeInfo.CHAR, 45, 10, "ZIP"), new DLITypeInfo("DealerPhone",DLITypeInfo.CHAR, 55, 7, "PHONE"), }; static DLISegment dealerSegment = new DLISegment("DealerSegment", "DEALER", dealerInfo, 61); // An array of DLITypeInfo objects to describe fields follows: static DLITypeInfo[] modelInfo = { new DLITypeInfo("ModelType",DLITypeInfo.CHAR, 1, 2, "MODTYPE"), new DLITypeInfo("ModKey",DLITypeInfo.CHAR, 3, 24, "MODKEY"), new DLITypeInfo("Make",DLITypeInfo.CHAR, 3, 10, "MAKE"), new DLITypeInfo("Model",DLITypeInfo.CHAR, 13, 10, "MODEL"), new DLITypeInfo("Year",DLITypeInfo.CHAR, 23, 4, "YEAR"), new DLITypeInfo("MSRP",DLITypeInfo.CHAR, 27, 5, "MSRP"), new DLITypeInfo("Count",DLITypeInfo.CHAR, 32, 2, "COUNT"), }; static DLISegment modelSegment = new DLISegment("ModelSegment", "MODEL", modelInfo, 37); // An array of DLITypeInfo objects to describe fields follows: static DLITypeInfo[] orderInfo = { new DLITypeInfo("OrderNo", DLITypeInfo.CHAR, 1, 6, "ORDNBR"), new DLITypeInfo("LastName", DLITypeInfo.CHAR, 7, 25,"LASTNME") new DLITypeInfo("FirstName", DLITypeInfo.CHAR, 32, 25,"FIRSTNME"), new DLITypeInfo("Date", DLITypeInfo.CHAR, 57, 10, "DATE"), new DLITypeInfo("Time", DLITypeInfo.CHAR, 67, 8, "TIME"), }; static DLISegment orderSegment = new DLISegment("OrderSegment", "ORDER", orderInfo, 74); // An array of DLITypeInfo objects to describe fields follows: static DLITypeInfo[] salesInfo = { new DLITypeInfo("SaleNo", DLITypeInfo.CHAR, 1, 4, "SALENUM"), new DLITypeInfo("SaleDate", DLITypeInfo.CHAR, 5, 8, "SALDATE"), new DLITypeInfo("LastName", DLITypeInfo.CHAR, 13, 25, "LASTNME"), }; static DLISegment salesSegment = new DLISegment("SalesSegment", "SALES", salesInfo, 37); static DLITypeInfo[] stockInfo = { new DLITypeInfo("StockVin", DLITypeInfo.CHAR, 1, 20, "STKVIN"), new DLITypeInfo("Color", DLITypeInfo.CHAR, 21, 10, "COLOR"), new DLITypeInfo("Price", DLITypeInfo.CHAR, 31, 5, "PRICE"), new DLITypeInfo("Lot", DLITypeInfo.CHAR, 36, 10, "LOT"), new DLITypeInfo("Warranty", DLITypeInfo.CHAR, 46, 1, "WRNTY"), }; static DLISegment stockSegment = new DLISegment("StockSegment", "STOCK", stockInfo, 46); // An array of DLISegment objects to describe PSB view static DLISegmentInfo[] segments = { 1 new DLISegmentInfo(dealerSegment, DLIDatabaseView.ROOT), 3 new DLISegmentInfo(modelSegment, 0), new DLISegmentInfo(OrderSegment, 1), 2 new DLISegmentInfo(salesSegment, 1), new DLISegmentInfo(stockSegment, 1), }; public DealerDatabaseView() { super("DLR_PSB", "DealerDB", "DLR_PCB1", segments); 4 } }
Figure 61. DLIDatabaseView Example Code IMS Java User’s Guide
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
In our dealership example, there is only a single PCB defined in the dealership PSB. If there were other PCBs defined, they would be added to the DLIDatabaseView by: 1. Providing a separate array of DLISegmentInfo objects for the additional PCB. 2. Calling the method addDatabase within our Dealer constructor after the call to super, and passing the reference name of the PCB, the real name of the PCB, and the variable defining the array of DLISegmentInfo objects.
DLISegment Example Using the extracted database name and segment names from Figure 60 on page 100, you create a DLISegment dealer. The numbers in the following list (for example, 1) are referenced in Figure 62. Note the following: v You create an array of DLITypeInfo objects, one entry for each field used by the application. 1 v Each DLITypeInfo object defines the name, type, starting offset, length, and optionally the name of the field in the DBD. If you want to search on a field in a DLITypeInfo object, add the name of the field as specified in the DBD. You can have more fields than those named in the DBD. For example the field “DealerAddr” is a character field that starts at offset 35 for a length of 20 bytes and is not defined in the DBD. 2 To search on a field, the field name must be defined in the DBD file, and the field name as listed in the DBD must be provided to the DLITypeInfo object. v The segment name, DEALER, is passed in the Dealer constructor to the DLISegment constructor with the array of DLITypeInfo objects and the length of the entire array. 3 The easiest way to calculate that length is to add the starting offset of the last field in the array to its length and subtract 1. In this example: 55 + 7 -1 = 61. static DLITypeInfo[] dealerInfo = new DLITypeInfo("DealerNo", new DLITypeInfo("DealerName", new DLITypeInfo("DealerAddr", 2
{ 1 DLITypeInfo.CHAR 1, 4, "DLRNO"), DLITypeInfo.CHAR 5, 30, "DLRNAME"), DLITypeInfo.CHAR 35, 20),
new DLITypeInfo("DealerCity", DLITypeInfo.CHAR 35, 10, "CITY"), new DLITypeInfo("DealerZip", DLITypeInfo.CHAR 45, 10, "ZIP") new DLITypeInfo("DealerPhone", DLITypeInfo.CHAR 55, 7, "PHONE"), }; static DLISegment dealerSegment = new DLISegment("DealerSegment", "DEALER", dealerInfo, 61); 3 Figure 62. Example DLISegment Code
Appendix A. Manually Creating IMS Java Metadata Classes
103
104
IMS Java User’s Guide
Appendix B. High Performance Java | |
This appendix provides the compile and runtime options for High Performance Java. This method, although supported, is not recommended. In this chapter: v “Compile and Runtime Options” v “Installation Verification Process” on page 107
Compile and Runtime Options IMS does not support setting environmental variables before running an application; instead, you must set any environmental variables needed by an application at compile time. The following options must be set at compile time: -lerunopts=″ENVAR″ Allows environment variables to be defined in the executable for use at runtime. Set the following environment variables with this option: CLASSPATH An environment variable used during runtime to locate class files. CLASSPATH must be set to point to the imsjava library code, and the hpj runtime library code. Default installation locations are: /usr/lpp/ims/imsjava71/imsjava.jll and /usr/lpp/hpj/lib, respectively. -lerunopts="ENVAR(’CLASSPATH=/usr/lpp/hpj/lib:/usr/lpp/ims /imsjava71/imsjava.jll’, ’IBMHPJ_HOME=/usr/lpp/hpj’)"
IBMHPJ_HOME Identifies the root of the hpj files, and is used to locate hpj libraries at runtime. It is typically /usr/lpp/hpj. LIBPATH Identifies additional locations for runtime to search for library files. In particular, it can be used to find a UNIX link to the IMS Java native code library if the installation default is changed. At installation, this link is /usr/lpp/ims/imsjava71/libJavTDLI.dll, which points to the PDSE member DFSCLIB. You can create the UNIX link libJavTDLI.so to point to DFSCLIB in any location included in the LIBPATH. -include Use this option of the hpj command to include objects in your executable. Objects that need to be included are those that are dynamically loaded at runtime. For example, if you provide your database view as a string instead of creating an instance of the view in your application, you must include that string in your executable. This option is necessary any time you are writing JDBC applications. You must include all database views. An example of the -include option follows: -include=dealership.application.DealerDatabaseView
-exclude Use this option of the hpj command to exclude objects from being statically bound to your executable. The exclude statements in Figure 63 on page 106 illustrate how to dynamically access the IMS Java classes:
© Copyright IBM Corp. 2000, 2002
105
-exclude=com.ibm.ims.base.* -exclude=com.ibm.ims.application.* -exclude=com.ibm.ims.db.*
Figure 63. -exclude statement example
-main=classname Use this option to specify the class that contains the main startup method, which is used as the main entry point for the executable. -make Use this option to rebind only those objects that have changed. Although you can use the -make option when building a Java executable or DLL for the first time, you normally use this option when you are doing incremental rebind to refresh an existing Java executable or DLL. -target=IMS Use this required option to indicate that the program will be an IMS application. -o=executable Use this option to explicitly name the Java executable or DLL that you are building in the hfs file system or as a PDSE (partitioned dataset extended) member. -alias=name Use this option to specify an alias or hierarchical file system (HFS), such as the name for a Java executable or DLL that is being written to a PDSE member. The option -alias must be specified for all Java DLLs that reside in PDSE members. Your application containing the main has to be in a PDSE. To build an application as an executable in a PDSE member named IMSAUTO, follow these steps: 1. Make the root of the source files the current directory: cd /u/usrt001
2. Compile the Java source files: javac dealership/application/*.java javac dealership/database/*.java
3. Bind the class files into an executable member named IMSAUTO of the PDSE AUTO.DEALERSHIP: hpj -make dealership.application.IMSAuto \ -main=dealership.application.IMSAuto \ -o="//’AUTO.DEALERSHIP(IMSAUTO)’" \ -alias=IMSAUTO \ -target=IMS \ -lerunopts="ENVAR(’CLASSPATH=/usr/lpp/hpj/lib:/usr/lpp/ims /imsjava71/imsjava.jll ’, ’IBMHPJ_HOME=/usr/lpp/hpj ’)" \ -exclude=com.ibm.ims.db.* \ -exclude=com.ibm.ims.application.* \ -include=dealership.application.DealerDatabaseView \ -exclude=com.ibm.ims.base.*
Figure 64. Binding the class files
106
IMS Java User’s Guide
Installation Verification Process The following are example steps to verify an IMS Java install. 1. Go to the directory in which IMS Java is installed: cd usr/lpp/ims/imsjava71
2. Compile the IVP Java programs: javac samples/ivp/*.java
3. Create the executable load module and put it in the IVP PGMLIB data set (which should be pre-allocated): hpj samples.ivp.IVP -main=samples.ivp.IVP \ -o="//’IVPEXEXX.PGMLIB(DFSIVP32)’" -alias=DFSIVP32 \ -target=IMS \ -lerunopts="ENVAR(’CLASSPATH=/usr/lpp/hpj/lib:/usr/lpp/ims /imsjava71/imsjava.jll ’, ’IBMHPJ_HOME=/usr/lpp/hpj ’)"
4. Add the IVP PGMLIB data set to the STEPLIB in the JCL that starts the IMS MPP region. In the installation verification process, this data set must come before any other data set with the same name (DFSIVP32) in the STEPLIB concatenation. The first data set with that name in the STEPLIB is the one that will be executed. STEPLIB DD DSN=IVPEXEXX.PGMLIB,DISP=SHR
5. Include the data set for the IMS Java class libraries and hpj class libraries in the STEPLIB: DD DD DD
DSN=hlq.SDFSJLIB,DISP=SHR DSN=VAJAVA.V2R0M0.SHPJMOD,DISP=SHR DSN=VAJAVA.V2R0M0.SHPOMOD,DISP=SHR
The HLQ (High Level Qualifier) is the PDSE that you specified during the installation process for IMS Java. 6. Change the version number of the HPJ to reflect the correct version of HPJ installed. 7. Submit the JCL to start the IMS MPP region. 8. Go to the IMS terminal and invoke the formatted screen for the transaction: /format IVTCC
An input screen as shown in Figure 65 on page 108 will be displayed:
Appendix B. High Performance Java
107
************************************************** * IMS INSTALLATION VERIFICATION PROCEDURE * ************************************************** TRANSACTION TYPE : CONVERSATIONAL DATE : 04/03/00 PROCESS LAST FIRST
CODE
(*1) :
NAME
(*1) PROCESS CODE ADD DELETE UPDATE DISPLAY TADD END
:
NAME
:
EXTENSION
NUMBER
:
INTERNAL
ZIP CODE
:
SEGMENT# :
Figure 65. Example of a Blank IMS Installation Verification Procedure Screen
9. Enter the appropriate input. Figure 66 shows an example for the display query: Figure 67 on page 109 displays the output of the transaction: ************************************************** * IMS INSTALLATION VERIFICATION PROCEDURE * ************************************************** TRANSACTION TYPE : CONVERSATIONAL DATE : 04/19/00 PROCESS CODE LAST FIRST
(*1)
NAME NAME
:
DISPLAY
:
LAST1
:
EXTENSION
NUMBER
:
INTERNAL
ZIP CODE
:
(*1) PROCESS CODE ADD DELETE UPDATE DISPLAY TADD END
SEGMENT# : Figure 66. Example IMS Installation Procedure Screen with Transaction Input Information
108
IMS Java User’s Guide
************************************************** * IMS INSTALLATION VERIFICATION PROCEDURE * ************************************************** TRANSACTION TYPE : CONVERSATIONAL DATE : 04/19/00 PROCESS LAST FIRST
CODE
(*1) :
NAME NAME
DISPLAY
:
LAST1
:
FIRST1
EXTENSION
NUMBER
:
8-111-1111
INTERNAL
ZIP CODE
:
D01/R01
ENTRY WAS DISPLAYED
(*1) PROCESS CODE ADD DELETE UPDATE DISPLAY TADD END
SEGMENT# :
Figure 67. Example IMS Installation Verification Procedure Screen with Transaction Output Information
Appendix B. High Performance Java
109
110
IMS Java User’s Guide
Bibliography This bibliography includes all the publications cited in this book, including the publications in the IMS library. | | | | | | | | | | | | | | | | | | | |
IBM Developer Kit for OS/390, Java 2 Technology Edition: New IBM Technology featuring Persistent Reusable Java Virtual Machines, SC34-6034 IMS Primer, SG24-5352 OS/390: Unix Systems Services Command Reference, SC28-1892 OS/390: Unix System Services File System Interface Reference, SC28-1909 OS/390: Unix Systems Services User’s Guide, SC28-1891 CICS Transaction Server for OS/390: CICS System Definition Guide, SC33-1682 WebSphere Application Server V4.0.1 for z/OS and OS/390 : Assembling Java 2 Platform, Enterprise Edition (J2EE) Applications, SA22-7836 WebSphere Application Server V4.0.1 for z/OS and OS/390 : System Management User Interface, SA22-7838
IMS Version 7 Library SC26-9419
ADB
SC26-9420
AS
SC26-9421
ATM
SC26-9422
APDB
SC26-9423
APDG
SC26-9424
APCICS
SC26-9425
APTM
SC26-9427
CG
SC26-9426
CQS
IMS Version 7 Administration Guide: Database Manager IMS Version 7 Administration Guide: System IMS Version 7 Administration Guide: Transaction Manager IMS Version 7 Application Programming: Database Manager IMS Version 7 Application Programming: Design Guide IMS Version 7 Application Programming: EXEC DLI Commands for CICS and IMS IMS Version 7 Application Programming: Transaction Manager IMS Version 7 Customization Guide IMS Version 7 Common Queue Server and Base Primitive Environment Guide and Reference
© Copyright IBM Corp. 2000, 2002
SC26-9436
CR
SC26-9428
DBRC
LY37-3738
DGR
LY37-3739
FAST
SC27-0832
IJUG
GC26-9429
IIV
GC26-9430
ISDT
SC26-9432
MIG
GC26-9433
MC1
GC26-1120
MC2
SC26-9434
OTMA
SC26-9435
OG
GC26-9437
RPG
SC26-9438
SOP
SC26-9440
URDBTM
SC26-9441
URS
IMS Version 7 Command Reference IMS Version 7 DBRC Guide and Reference IMS Version 7 Diagnosis Guide and Reference IMS Version 7 Failure Analysis Structure Tables (FAST) for Dump Analysis IMS Version 7 IMS Java User’s Guide IMS Version 7 Installation Volume 1: Installation and Verification IMS Version 7 Installation Volume 2: System Definition and Tailoring IMS Version 7 Master Index and Glossary IMS Version 7 Messages and Codes, Volume 1 IMS Version 7 Messages and Codes, Volume 2 IMS Version 7 Open Transaction Manager Access Guide IMS Version 7 Operations Guide IMS Version 7 Release Planning Guide IMS Version 7 Sample Operating Procedures IMS Version 7 Utilities Reference: Database and Transaction Manager IMS Version 7 Utilities Reference: System
Supplementary Publications GC26-9431
LPS
SC26-9439
SOC
IMS Version 7 Licensed Program Specifications IMS Version 7 Summary of Operator CommandsSummary of Operator Commands
Publication Collections LK3T-3526 LBOF5294
CD
IMS Version 7 Licensed Product Kit: Online Library Hardcopy Licensed Bill of Forms (LBOF): and CD IMS Version 7 Hardcopy and Online Library
111
Publication Collections SBOF5297
SK2T-0730 SK2T-6700
112
Hardcopy Unlicensed Bill of Forms (SBOF): IMS Version 7 Unlicensed Hardcopy Library CD IBM Online Library: Transaction Processing and Data CD IBM Online Library OS/390
IMS Java User’s Guide
Index Special characters -exclude 105 -include 105
A abends 0118 93 0475 94 batch run failure 94 commit failure 93 description 93 ABENDU0118 93 ABENDU0475 94 adding Trace statements to applications aggregate keywords 35 AIB interface 3 AIBERRXT 93 applications batch 2 CICS environment 59 DB2 environment 59 JBP 2 JMP 2 message driven 2 message processing, building 46 non-message driven 2 processing 46 programming 42 that work with IMS 45 asterisk operator 38
B batch programs 45 batch run failure 94 BIGINT data type 32 BINARY data type 32 BIT data type 32 buffers main storage 46 byte data type 32
C CHAR data type 32 CICS configuring for IMS Java 13 CICS environment IMS Java application 59 installation verification 14 overview 2 programming model 59 restrictions 13 system requirements 13 class DLIDatabaseView 41 © Copyright IBM Corp. 2000, 2002
97
class (continued) DLIRecord 41 DLISegment 41 DLISegmentInfo 41 DLITypeInfo 41 java.sql.DatabaseMetaData 31 java.sql.Driver 31 java.sql.Statement 31 SSAQualificationStatement 41 CLASSPATH 16 COBOL copybook types 33 mapping to IMS 33 command input 46 commit 31 commit failure 93 configuration CICS environment 13 WebSphere for z/OS environment 9 Connection object executing 29 Connection.commit 31 Connection.rollback 31 Connection.setAutoCommit 31 control statements DLIModel utility 62, 66 example 85 format 68 including 73 syntax 74 typical sequence 67 when to use 67 controlling the amount of tracing 96 conventions naming 28 conversational transactions 52 copybook types 33
D data types conversion 32 mapped to COBOL 33 database metamodel XMI 65 database segment description 27 DATE data type 32 DB2 environment configuring 15 ENVAR settings 16 IMS Java applications 59 installation verification 17 overview 2 programming model 59 restrictions 15 setup 15 system requirements 15
113
DB2_HOME 16 DBD (Database Definition) example 25 DD statements 75 dealership sample overview 23 debugging 91 IMSTrace 96 default values assigning 99 DELETE statement 39 design process 1 determining problems in your applications IMSTrace 96 DFHJVMPR 13 DFSDLA00 93 DFSJVMAP 5 DFSJVMEV 5 DFSMODEL member 19 DFSTMS00 93 DL/I data accessing 43 DL/I PCB status codes 93 DL/I status codes mapping to exceptions 91 DLIConnection 41, 91 creating 42 DLIDatabaseView 41 example 101 mapping the DBD 100 DLIDriver loading 29 registering 29 DLIException 91 DLIModel Java Report database summary 64 example 25 fields 27 PCBs 26 DLIMODEL MVS Procedure preparing 19 DLIModel utility control statements 62, 66 description 61 inputs and outputs 62 limitations 63 logical relationship example 79 metadata classes creating 61 MVS procedure EXEC statement 21 script file 20 MVS USS prompt 21 output types 64 overview 61 procedure 74 PSB requirements 63 report 61 restrictions 64 running 74 running as MVS job 74
114
IMS Java User’s Guide
DLIModel utility (continued) running from USS 77 secondary index example 83 setup 19 MVS procedure 19 simple example 77 use 27 using 61, 77 DLIRecord 41 DLISegment 41 example 103 DLISegmentInfo 41 DLITypeInfo 41 DLITypeInfoList 55 doBegin() implementing 48 documenting an application’s flow of control DOUBLE data type 32 driver registering with DriverManager 29 DriverManager 30 DSNAME parameter 75 dump processing 94
E EAR (Enterprise Archive) 11 EJB (Enterprise Java Bean) deploying 9 overview 2 EJB (Enterprise Java Bean)deploying 11 Enterprise Java Bean (EJB) See EJB (Enterprise Java Bean) 2 ENVIRON 5 environments CICS configuring 13 installation verification 14 overview 2 restrictions 13 system requirements 13 DB2 configuring 15 installation verification 17 overview 2 restrictions 15 general restrictions 3 setup 3 system requirements 3 IMS configuration 4 installation verification 6 JMP 4 overview 1 restrictions 2, 4 setup 4 system requirements 4 WebSphere for z/OS installation verification 12 overview 2
96
environments (continued) WebSphere for z/OS (continued) restrictions 8 setup 8 system requirements 8 Environments WebSphere for z/OS EJB, deploying 11 exceptions description 91 mapping to DL/I status codes 91 EXEC statement parameters 75
F Field statement 67, 71 fields default values, assigning float data type 32 FROM clause 37
99
G genXMI parameter 65 getAIB 91 getFunction 91 getNextException 92 getStatusCode 91 GU message failure 93
H HFS (Hierarchic File System) 3 High Performance Java See HPJ (High Performance Java) HPJ (High Performance Java) compile options 105 installation verification 107 runtime options 105
I import statements 29 IMS application processing 45 applications in Java 45 call analyzer module 93 IMS databases (DBD) database definition 99 accessing 23 JDBC 24 mapping to Java classes 99 relational, compared to 28 IMS environment configuration 4 installation verification 6 overview 1 restrictions 2 IMS Java alias 28
107
IMS Java (continued) data type support 32 databases supported 1 dependent regions 1 messages supported 1 overview 1 prerequisite knowledge xv restrictions 3 system requirements 3 IMS Java hierarchic database interface overview 1, 23 SSAs 23 IMS JDBC Connector 9 IMS JDBC Resource Adapter configuring 9 deploying 10 IMSApplication subclassing 48 IMSException 91 IMSFieldMessage 57 subclassing 47 IMSJdbcCustomService.xml 10 IMSMessageQueue 92 IMSMessageQueue.getUniqueMessage 56 IMSTrace 96 include option 105 Include statement 73 index field secondary 73 initiating IMSTrace 96 input command 46 message switch 46 messages defining 47 transaction message 46 INSERT statement 38 WHERE clause 38 installation verification CICS environment 14 DB2 environment 17 IMS environment 6 WebSphere for z/OS environment 12 int data type 32 INTEGER data type 32 IVP (installation verificaiton program) See installation verification 14
J J2EE server configuring 9 EJB, deploying 11 IMS JDBC Resource Adapter, locating JVM properties 10 modifying properties 9 overview 2 java batch processing (JBPs) 45 Java classes mapping to IMS databases 99 Java data types 32
9
Index
115
java message processing (JMPs) 45 JAVA_HOME 16 java.math.BigDecimal 32 java.sql.Connection 30 java.sql.DatabaseMetaData 31 java.sql.Date 32 java.sql.Driver 31 java.sql.PreparedStatement 32 java.sql.ResultSet 32 java.sql.ResultSetMetaData 32 java.sql.Statement 31 java.sql.Time 32 java.sql.Timestamp 32 JAVAENV data set 16 JBP (Java Batch Processing) configuring 5 overview 2 JBPs 45 JDBC classes 27 Connection object, returning 29 data types 32 field names 27 IMS databases accessing 24 interfaces, limitations 30 overview 1, 23 prerequisite knowledge xv JMP (Java Message Processing) configuring 4 overview 2 JMPs 45 JVM master 4 worker 5 JVM regions, overview 1 JVMOPMAS 4 JVMOPWRK 5
K keywords aggregate 35 supported 35
L LIBPATH 16 local transactions 3 logical relationships DLIModel utility example 79 logical terminal (LTERM) 54 long data type 32 LTERM 54
M main storage buffers main() 48 master JVM 4
116
46
IMS Java User’s Guide
message processing application building 46 message processing applications message queue 46 message switch input 46 messages input defining 47 processing multiple 56 retrieving 56 message queue in Java 46 multi-segment 54 output, defining 47 reading and writing 46 repeating structures accessing 55 SPA 52 metadata class creating 24 metadata classes creating 61 creating manually 99 generated 64 multi-segment messages 54
46
N naming conventions SQL 35 nested structures accessing 55
O object DLIConnection 41 DLIConnection, creating 42 DriverManager 30 java.sql.Connection 30 SSA 41 ODBA (Open Database Access) options include 105 Options statement 66, 68 output messages defining 47
9
P P processing option 3 package database 30 PACKEDDECIMAL data type 32 PARM parameter 75 path call 38 PCB statement 67 prepared statement 40 PreparedStatement object 29, 36 prerequisite knowledge xv problem determination 91 PROC statement parameters 75
processing applications 46 processing dumps 94 program types 45 programming models CICS environment 59 DB2 environment 59 JBP 51 JMP 50 PRSUFFIX 14 PSB metadata class 61 XMI description 61 PSB (Program Specification Block) example 25 IMS Java metadata classes, relationship PSB statement 66, 70
Q queuing messages
46
R Rational Rose metamodel 66 reason codes 93 repeating structures accessing 55 report DLIModel utility 61 requirements, system 3 restrictions 3 CICS environment 13 DB2 environment 15 WebSphere for z/OS 8 ResultSet iterating 29 return codes 93
S sample message processing application 46 scratch pad area (SPA) 52 secondary index DLIModel utility example 83 secondary index field 73 SEGM statement 67, 70 segment instances querying 29 segment search arguments (SSAs) 41 segments default values, assigning 99 SELECT statement asterisk operator 38 description 35 setting up tracing 96 short data type 32 SMALLINT data type 32 SPA 52, 54
24
SPA message defining 53 SQL DELETE statement 39 FROM clause 37 INSERT statement 38 keywords 34, 35 naming conventions 35 prepared statement 40 referring to Java Report 64 SELECT statement 35 supported grammar 34 UPDATE statement 39 using a Statement object 36 SQL query example 28 SQLException 92 SQLquery naming conventions 28 SQLstate 92 SSA 41 SSAList 41 creating an 42 DL/I data, accessing 43 SSAQualificationStatement 41 SSAs 37, 41 starting IMSTrace 96 Statement object 36 retrieving 29 status codes 93 CR 93 mapping 91 STDENV DD statement 75 STDERR DD statement 76 STDOUT DD statement 75 Stored Procedures See DB2 environment 15 String data type boolean data type 32 structures nested accessing 55 sync point failure 93 processor 93 SYSOUT parameter 75 system requirements 3 CICS environment 13 DB2 environment 15 WebSphere for z/OS environment SYSTSIN DD statement 76
8
T TIME data type 32 TIMESTAMP data type 32 TINYINT data type 32 TMPREFIX 14 TMSUFFIX 16 tracing IMS Java library routines
96 Index
117
tracing (continued) IMSTrace 96 Trace statements, adding 97 transaction message input 46 transactions conversational 52 local 3 turning on IMSTrace 96 types data, mapped to COBOL 33 supported 32
U UPDATE statement 39 URL (universal resource locator) USS (Unix System Services) DLIModel utility, running 21
30
V VARCHAR data type
32
W WebSphere for z/OS DRA startup table 9 EJB, deploying 9, 11 IMS JDBC Resource Adapter 9 J2EE server 2 ODBA 9 WebSphere for z/OS environment accessing IMS 9 configuring 9 DRA startup table 9 installation verification 12 overview 2 restrictions 8 setup 8 system requirements 8 WHERE clause 38 worker JVM 5
X Xdfld statement 73 XMI creating 61 metamodel 65 XOPEN SQLstate 92
Z ZONEDECIMAL data type
118
IMS Java User’s Guide
32
Readers’ Comments — We’d Like to Hear from You IMS Version 7 IMS Java User’s Guide Publication No. SC27-0832-02 Overall, how satisfied are you with the information in this book?
Overall satisfaction
Very Satisfied h
Satisfied h
Neutral h
Dissatisfied h
Very Dissatisfied h
Neutral h h h h h h
Dissatisfied h h h h h h
Very Dissatisfied h h h h h h
How satisfied are you that the information in this book is:
Accurate Complete Easy to find Easy to understand Well organized Applicable to your tasks
Very Satisfied h h h h h h
Satisfied h h h h h h
Please tell us how we can improve this book:
Thank you for your responses. May we contact you?
h Yes
h No
When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate without incurring any obligation to you.
Name Company or Organization Phone No.
Address
SC27-0832-02
___________________________________________________________________________________________________
Readers’ Comments — We’d Like to Hear from You
Cut or Fold Along Line
_ _ _ _ _ _ _Fold _ _ _and _ _ _Tape _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Please _ _ _ _ _do _ _not _ _ staple _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Fold _ _ _and _ _ Tape ______ NO POSTAGE NECESSARY IF MAILED IN THE UNITED STATES
BUSINESS REPLY MAIL FIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK POSTAGE WILL BE PAID BY ADDRESSEE
IBM Corporation H150/090 555 Bailey Avenue San Jose, CA 95141-9989
_________________________________________________________________________________________ Fold and Tape Please do not staple Fold and Tape
SC27-0832-02
Cut or Fold Along Line
Program Number: 5655-B01
Printed in U.S.A.
SC27-0832-02
Spine information:
IMS Version 7
IMS Java User’s Guide
IMS Java User’s Guide
SC27-0832-02
IMS Version 7
IMS Java User’s Guide
SC27-0832-02
Note Before using this information and the product it supports, be sure to read the general information under “Notices”.
Third Edition (August 2002) (Softcopy Only) This edition replaces and makes obsolete the previous edition, SC27-0832-01. This edition is available in softcopy format only. The technical changes for this version are summarized under “Summary of Changes” on page xvii. The technical changes for this edition are indicated by a vertical bar to the left of a change. © Copyright International Business Machines Corporation 2000, 2002. All rights reserved. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
Contents Figures
. . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
| |
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . xv Prerequisite Knowledge . . . . . . . . . . . . . . . . . . . . . . xv Change Indicators . . . . . . . . . . . . . . . . . . . . . . . . xv
| |
Summary of Changes . . . . . . . . . . . . . . . . . . . . . xvii Changes to The Current Edition of This Book for IMS Version 7 . . . . . . xvii Library Changes for IMS Version 7 . . . . . . . . . . . . . . . . . xvii
| | | | | |
Chapter 1. Overview of IMS Java . . . . Design Process . . . . . . . . . . . IMS Environment Overview . . . . . . . WebSphere for z/OS Environment Overview CICS Environment Overview . . . . . . DB2 Environment Overview. . . . . . .
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Chapter 2. Setting Up Your Environment for IMS Java. . . . . . . . . . 3 System Requirements for All Environments . . . . . . . . . . . . . . . 3 General Restrictions . . . . . . . . . . . . . . . . . . . . . . . 3 IMS Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 IMS System Requirements . . . . . . . . . . . . . . . . . . . . 4 IMS Restrictions . . . . . . . . . . . . . . . . . . . . . . . . 4 IMS Configuration . . . . . . . . . . . . . . . . . . . . . . . 4 Configuring a JMP Region . . . . . . . . . . . . . . . . . . . 4 Configuring a JBP Region . . . . . . . . . . . . . . . . . . . 5 IMS Installation Verification . . . . . . . . . . . . . . . . . . . . 6 WebSphere for z/OS Setup . . . . . . . . . . . . . . . . . . . . . 8 WebSphere for z/OS System Requirements. . . . . . . . . . . . . . 8 WebSphere for z/OS Restrictions . . . . . . . . . . . . . . . . . 8 WebSphere for z/OS Configuration . . . . . . . . . . . . . . . . . 9 Configuring the WebSphere for z/OS J2EE Server for IMS Access . . . . 9 Configuring the WebSphere for z/OS J2EE Server to Locate the IMS JDBC Resource Adapter . . . . . . . . . . . . . . . . . . . . . 9 Deploying an Instance of the IMS JDBC Resource Adapter . . . . . . 10 Deploying an EJB onto a WebSphere for z/OS J2EE Server . . . . . . 11 WebSphere for z/OS Installation Verification . . . . . . . . . . . . . 12 CICS Setup . . . . . . . . . . . . . . . . . . . . . . . . . . 13 CICS System Requirements . . . . . . . . . . . . . . . . . . . 13 CICS Restrictions . . . . . . . . . . . . . . . . . . . . . . . 13 CICS Configuration . . . . . . . . . . . . . . . . . . . . . . 13 Installation Verification . . . . . . . . . . . . . . . . . . . . . 14 DB2 Setup . . . . . . . . . . . . . . . . . . . . . . . . . . 15 DB2 System Requirements . . . . . . . . . . . . . . . . . . . 15 DB2 Restrictions . . . . . . . . . . . . . . . . . . . . . . . 15 DB2 Configuration. . . . . . . . . . . . . . . . . . . . . . . 15 ENVAR Settings for the JAVAENV Data Set . . . . . . . . . . . . 16 DB2 Installation Verification . . . . . . . . . . . . . . . . . . . 17 © Copyright IBM Corp. 2000, 2002
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
1 1 1 2 2 2
iii
| | |
DLIModel Utility Setup . . . . . . . . . . . . . . . . . . . . . . 19 Preparing the DLIMODEL MVS Procedure . . . . . . . . . . . . . . 19 Preparing to Run From the MVS USS Prompt . . . . . . . . . . . . 21
| | | | | | | | | | | | | | | | | | | | | | | | | |
Chapter 3. Accessing an IMS Database . . . . Introduction to the Example Environment . . . . JDBC Access Method . . . . . . . . . . . Describing Your IMS Databases to IMS Java . . Using JDBC to Access an IMS Database . . . Classes and Field Names . . . . . . . . PCB-Qualifying SQL Queries. . . . . . . Writing an Application that Uses JDBC . . . Supported Data Types in IMS Java . . . . . General Mappings from COBOL Copybook Types Types . . . . . . . . . . . . . . . Supported SQL Grammar . . . . . . . . . . SELECT . . . . . . . . . . . . . . . Segment-Qualifying Fields. . . . . . . . FROM . . . . . . . . . . . . . . . . WHERE . . . . . . . . . . . . . . . INSERT . . . . . . . . . . . . . . . DELETE . . . . . . . . . . . . . . . UPDATE . . . . . . . . . . . . . . . JDBC Prepared Statements for SQL . . . . . Recommendations for JDBC . . . . . . . . IMS Java Hierarchic Database Interface . . . . Application Programming Using DLIConnection . Creating a DLIConnection Object . . . . . . Building SSAs . . . . . . . . . . . . . Accessing DL/I Data using SSAs . . . . .
|
Chapter 4. Writing a Java Application Program . . . . . . . IMS Applications . . . . . . . . . . . . . . . . . . . Overview of IMS Application Processing . . . . . . . . . Running Java Applications. . . . . . . . . . . . . . Message Queuing. . . . . . . . . . . . . . . . . Reading and Writing Messages to the Message Queue in Java Building an IMS Java Application by Example . . . . . . . Using IMS Java to Build a Message Processing Application . Programming Models for IMS Java Applications . . . . . . . JMP Programming Models . . . . . . . . . . . . . JBP Programming Models . . . . . . . . . . . . . . Additional Programming Considerations . . . . . . . . . . Conversational Transactions . . . . . . . . . . . . . Handling Multi-Segment Messages . . . . . . . . . . Coding and Accessing Messages with Repeating Structures . Flexible Reading of Multiple Input Messages . . . . . . . CICS Applications . . . . . . . . . . . . . . . . . . . DB2 Stored Procedures . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . .
45 45 45 46 46 46 46 46 49 50 51 52 52 54 55 56 59 59
Chapter 5. DLIModel Utility . . . . . . . . . . DLIModel Utility Overview . . . . . . . . . . . Requirements and Restrictions of the DLIModel Utility Requirements . . . . . . . . . . . . . . Restrictions . . . . . . . . . . . . . . . Output Types of the DLIModel Utility . . . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . .
61 61 63 63 63 64
| | |
|
| | | | | |
iv
IMS Java User’s Guide
. . . . . . . . . to . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . IMS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . and Java Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . .
23 23 24 24 27 27 28 29 32 33 34 35 35 37 37 38 39 39 40 40 41 42 42 42 43
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
|
|
| | | | | |
IMS Java Metadata Classes . . . . . . . . . . DLIModel Java Report . . . . . . . . . . . . PSB Description . . . . . . . . . . . . . PCB Description . . . . . . . . . . . . . Segment Description . . . . . . . . . . . . Field Description . . . . . . . . . . . . . XMI Description of the Databases . . . . . . . . DLIModel Trace . . . . . . . . . . . . . . Control Statements for the DLIModel Utility . . . . . Control Data Set Rules . . . . . . . . . . . . Control Statement Rules . . . . . . . . . . . Control Statement Syntax . . . . . . . . . . . OPTIONS Statement. . . . . . . . . . . . PSB Statement . . . . . . . . . . . . . . PCB Statement . . . . . . . . . . . . . . SEGM Statement . . . . . . . . . . . . . FIELD Statement . . . . . . . . . . . . . XDFLD Statement. . . . . . . . . . . . . INCLUDE Statement . . . . . . . . . . . . Comment Statement . . . . . . . . . . . . Running the DLIModel Utility . . . . . . . . . . . Running the DLIModel Utility as an MVS Job . . . . PROC Statement Parameters . . . . . . . . Step 1 EXEC Statement Parameters . . . . . . Step 1 DD Statements . . . . . . . . . . . Step 2 EXEC Statement Parameters . . . . . . Step 2 DD Statements . . . . . . . . . . . Running the DLIModel Utility From MVS Unix Systems Examples of Using the DLIModel Utility . . . . . . . Example 1. Simple Example . . . . . . . . . . Example 2. Example With a Logical Relationship . . Example 3. Example With a Secondary Index . . . Example 4. Example with Multiple Control Statements
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Services . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
64 64 64 64 64 64 65 66 66 66 68 68 68 70 70 70 71 73 73 74 74 74 75 75 75 76 76 77 77 77 79 83 85
Chapter 6. Problem Determination . . . . . . . . Exceptions . . . . . . . . . . . . . . . . . How Exceptions Map to DL/I Status Codes . . . . SQLExceptions . . . . . . . . . . . . . . . Sync Point Failure. . . . . . . . . . . . . . . GU Message Failure . . . . . . . . . . . . . . Abends. . . . . . . . . . . . . . . . . . . ABENDU0118 - Commit Failure . . . . . . . . . ABENDU0475 - Batch Run Failure . . . . . . . Processing Dumps . . . . . . . . . . . . . DLIModel Messages . . . . . . . . . . . . . . IMSTrace . . . . . . . . . . . . . . . . . . Initiating IMSTracing . . . . . . . . . . . . . Setting up Tracing for the IMS Java Library Routines . Adding Trace Statements to Your Application . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
91 91 91 92 93 93 93 93 94 94 94 96 96 96 97
Appendix A. Manually Creating IMS Java Metadata Mapping an IMS Database in Java Classes . . . . IMS Database Definition (DBD) . . . . . . . . Adding Default Values for Fields of a Segment . . Mapping the PSB to DLIDatabaseView . . . . DLIDatabaseView Example . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
. . . . . . . . . . . . . . .
Classes . . . . . . . . . . . . . . . . . . . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. 99 . 99 . 99 . 99 . . . . . . 100 . . . . . . 101 Contents
v
DLISegment Example . . . . . . . . . . . . . . . . . . . . . 103
|
Appendix B. High Performance Java . . . . . . . . . . . . . . . 105 Compile and Runtime Options . . . . . . . . . . . . . . . . . . . 105 Installation Verification Process . . . . . . . . . . . . . . . . . . 107 Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . 111 IMS Version 7 Library . . . . . . . . . . . . . . . . . . . . . . 111 Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
vi
IMS Java User’s Guide
Figures | | | | | | | | | | | | | | | | | | |
|
|
| | | | | | | | | | | | | | | | | | | | | | | |
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. 39. 40. 41. 42. 43. 44. 45. 46. 47. 48. 49. 50. 51. 52. 53.
Example of a Blank IMS Installation Verification Procedure Screen . . . . . . . . . . Example IMS Installation Procedure Screen with Transaction Input Information . . . . . Example IMS Installation Verification Procedure Screen with Transaction Output Information Example Database Hierarchy . . . . . . . . . . . . . . . . . . . . . . . Example PSB Definition . . . . . . . . . . . . . . . . . . . . . . . . . DBD Sample Definition . . . . . . . . . . . . . . . . . . . . . . . . . The IMS Java Summary Report . . . . . . . . . . . . . . . . . . . . . . IMS DB Segments and Fields with Their Corresponding DB2 Tables and Columns . . . PCB-Qualifying SQL Query Example . . . . . . . . . . . . . . . . . . . . JDBC Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . Establish a Database Connection . . . . . . . . . . . . . . . . . . . . . . Example of SELECT Query Results . . . . . . . . . . . . . . . . . . . . . Sample Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample INSERT Statement . . . . . . . . . . . . . . . . . . . . . . . . Sample DELETE Statement . . . . . . . . . . . . . . . . . . . . . . . . Sample UPDATE Statement. . . . . . . . . . . . . . . . . . . . . . . . Creating a DLIConnection Object . . . . . . . . . . . . . . . . . . . . . . Creating an SSAList . . . . . . . . . . . . . . . . . . . . . . . . . . Subclass IMSFieldMessage: Input Message Sample Code . . . . . . . . . . . . Subclass IMSFieldMessage: Output Message Sample Code . . . . . . . . . . . . Subclass IMSApplication Sample Code . . . . . . . . . . . . . . . . . . . Defining a SPA Message . . . . . . . . . . . . . . . . . . . . . . . . . Reading the SPA Message . . . . . . . . . . . . . . . . . . . . . . . . Writing the SPA Message. . . . . . . . . . . . . . . . . . . . . . . . . Example Output Message . . . . . . . . . . . . . . . . . . . . . . . . Defining the Primary Input Message . . . . . . . . . . . . . . . . . . . . . Creating the Input Messages . . . . . . . . . . . . . . . . . . . . . . . Message Reading Logic . . . . . . . . . . . . . . . . . . . . . . . . . The DLIModel Utility Inputs and Outputs . . . . . . . . . . . . . . . . . . . Sample DLIModel Utility PROC . . . . . . . . . . . . . . . . . . . . . . Physical DBD for Simple Example . . . . . . . . . . . . . . . . . . . . . PSB for Simple Example . . . . . . . . . . . . . . . . . . . . . . . . . Minimal MVS JCL stream. . . . . . . . . . . . . . . . . . . . . . . . . Control Data Set for Simple Example . . . . . . . . . . . . . . . . . . . . DLIModel Java Report for Simple Example . . . . . . . . . . . . . . . . . . EMPDB2 Physical DBD for Logical Relationship Example . . . . . . . . . . . . . DEALDB2 Physical DBD for Logical Relationship Example . . . . . . . . . . . . Logical DBD for Logical Relationship Example . . . . . . . . . . . . . . . . . PSB with Field-Level Sensitivity for Logical Relationship Example . . . . . . . . . . Control Data Set for Logical Relationship Example . . . . . . . . . . . . . . . DLIModel Java Report for Logical Relationship Example . . . . . . . . . . . . . DBD for Secondary Index Example . . . . . . . . . . . . . . . . . . . . . Logical DBD for Secondary Index Example . . . . . . . . . . . . . . . . . . PSB for Secondary Index Example . . . . . . . . . . . . . . . . . . . . . MVS USS Command for Secondary Index Example . . . . . . . . . . . . . . . Control Data Set for Secondary Index Example . . . . . . . . . . . . . . . . DLIModel Java Report for Secondary Index Example . . . . . . . . . . . . . . Physical DBD for Multiple Control Statements Example. . . . . . . . . . . . . . PSB for Multiple Control Statements Example . . . . . . . . . . . . . . . . . MVS USS Command for Control Statements Example . . . . . . . . . . . . . . Top-Level Control Data Set for Multiple Control Statements Example. . . . . . . . . Second-Level Control Data Set for Multiple Control Statements Example . . . . . . .
© Copyright IBM Corp. 2000, 2002
. . . 7 . . . 7 . . . 8 . . . 24 . . . 25 . . . 25 . . . 26 . . . 28 . . . 29 . . . 30 . . . 31 . . . 36 . . . 37 . . . 37 . . . 38 . . . 39 . . . 39 . . . 42 . . . 43 . . . 47 . . . 48 . . . 49 . . . 53 . . . 53 . . . 54 . . . 56 . . . 57 . . . 58 . . . 59 . . . 62 . . . 75 . . . 78 . . . 78 . . . 78 . . . 78 . . . 79 . . . 80 . . . 80 . . . 81 . . . 81 . . . 82 . . . 82 . . . 83 . . . 84 . . . 84 . . . 84 . . . 84 . . . 85 . . . 86 . . . 86 . . . 86 . . . 87 . . . 88
vii
| 54. DLIModel Java Report for Multiple Control Statements Example . . . . . . | 55. Database access methods of DLIConnection . . . . . . . . . . . . . 56. IMSException Sample . . . . . . . . . . . . . . . . . . . . . . | 57. Setting a Trace within a Static Method . . . . . . . . . . . . . . . . 58. Setting Up IMSTrace . . . . . . . . . . . . . . . . . . . . . . | 59. Example Database and Segments . . . . . . . . . . . . . . . . . | 60. DBD Sample Definition . . . . . . . . . . . . . . . . . . . . . | 61. DLIDatabaseView Example Code . . . . . . . . . . . . . . . . . | 62. Example DLISegment Code . . . . . . . . . . . . . . . . . . . 63. -exclude statement example . . . . . . . . . . . . . . . . . . . 64. Binding the class files . . . . . . . . . . . . . . . . . . . . . 65. Example of a Blank IMS Installation Verification Procedure Screen . . . . . 66. Example IMS Installation Procedure Screen with Transaction Input Information 67. Example IMS Installation Verification Procedure Screen with Transaction Output
viii
IMS Java User’s Guide
. . . . . .
. . . . . .
. . . . . .
. . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Information
. . . . . .
. . . . . . . . . . . . .
. 89 . 92 . 92 . 97 . 97 . 99 . 100 . 102 . 103 . 106 . 106 . 108 . 108 109
Tables 1. 2. 3. 4. 5. 6. | 7. | | | | |
Supported Data Types . . . . . . . . . . . . . . . . . ResultSet.getxxx Methods to Retrieve JDBC Types . . . . . . Mapping from COBOL to IMS and Java . . . . . . . . . . DLITypeInfo Constants and Java Types based on PICTURE clause CopyBook Formats Mapped to IMS Java Types . . . . . . . Status Code, Reason, and Return Code . . . . . . . . . . Status Code, Reason, and Return Code . . . . . . . . . .
© Copyright IBM Corp. 2000, 2002
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
32 33 34 34 34 93 93
ix
x
IMS Java User’s Guide
Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user’s responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs © Copyright IBM Corp. 2000, 2002
xi
and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation J46A/G4 555 Bailey Avenue San Jose, CA 95141-1099 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurement may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. All statements regarding IBM’s future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only. This information is for planning purposes only. The information herein is subject to change before the products described become available. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrates programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. You may copy, modify, and distribute these sample programs in any form without payment to IBM for the purposes of developing, using, marketing, or distributing application programs conforming to IBM’s application programming interfaces.
xii
IMS Java User’s Guide
Each copy or any portion of these sample programs or any derivative work, must include a copyright notice as follows: © (your company name) (year). Portions of this code are derived from IBM Corp. Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rights reserved. If you are viewing this information softcopy, the photographs and color illustrations may not appear.
Trademarks The following terms are trademarks of the IBM Corporation in the United States or other countries or both: BookManager DB2 CICS IBM IMS
MVS OS/390 WebSphere z/OS
Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc., in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Other company, product, and service names may be trademarks or service marks of others.
Notices
xiii
xiv
IMS Java User’s Guide
Preface | | |
This book explains how to configure your system for IMS Java application support, how to build IMS Java metadata classes using the DLIModel utility, and how to write Java application programs that access IMS databases. This softcopy book is available only in PDF and BookManager formats. This book is available on the IMS Version 7 Licensed Product Kit (LK3T-3526). You can also get the most current versions of the PDF and BookManager formats by going to the IMS Web site at www.ibm.com/ims and linking to the Library page.
|
Prerequisite Knowledge
| | | |
To configure your system for IMS Java, you must understand system administration for your system (IMS, WebSphere Application Server, CICS, or DB2). For IMS system administration, you should know the concepts in IMS Version 7 Administration Guide: System.
| | |
To create IMS Java metadata classes, which is a required step in writing IMS Java applications, you must understand IMS databases. IMS database concepts are described in IMS Version 7 Administration Guide: Database Manager.
| | |
To write IMS Java applications, you must thoroughly understand the Java language and JDBC. This book assumes that you know Java and JDBC. It does not explain any Java or JDBC concepts.
| | |
Change Indicators Technical changes are indicated in this publication by a vertical bar ( | ) to the left of the changed text.
© Copyright IBM Corp. 2000, 2002
xv
xvi
IMS Java User’s Guide
Summary of Changes |
Changes to The Current Edition of This Book for IMS Version 7
| |
This edition, which is available in softcopy format only, includes technical and editorial changes.
| |
This book has undergone major organizational changes in addition to technical changes.
| |
This book contains new information about the following enhancements to IMS Java application support: v JMP and JBP IMS dependent regions for a Java Virtual Machine (JVM) environment v DLIModel utility for creating IMS Java metadata classes v WebSphere Application Server for OS/390 and z/OS, CICS Transaction Server z/OS, and DB2 UDB for z/OS and OS/390 Stored Procedures support
| | | | | | |
Library Changes for IMS Version 7
| | | | | | | |
The major change to the IMS Version 7 library is that it is available not only in hardcopy and in softcopy on BookManager, but also in softcopy Portable Document Format (PDF). The complete library is available in BookManager and PDF on the IMS Version 7 product kit CD-ROM (LK3T-3526). The unlicensed IMS Version 7 softcopy library is available on the Transaction Processing and Data CD-ROM (SK2T-0730) and the OS/390 Collection CD-ROM (SK2T-6700) in BookManager. The unlicensed IMS Version 7 softcopy library is available in BookManager and PDF on the Web at http://www.ibm.com/ims
| | | | | | | | | | |
Other changes include changes to these following books: v IMS Version 7 Common Queue Server and Base Primitive Environment Guide and Reference The book formerly titled IMS/ESA Common Queue Server Guide and Reference in the Version 6 library is called IMS Version 7 Common Queue Server and Base Primitive Environment Guide and Reference. The IMS Version 7 Common Queue Server and Base Primitive Environment Guide and Reference is divided into two parts: ″Part 1: Common Queue Server,″ and ″Part 2: Base Primitive Environment.″ The IMS Version 7 Common Queue Server and Base Primitive Environment Guide and Reference is now an unlicensed book. v IMS Version 7 Command Reference The book formerly titled IMS/ESA Operator’s Reference in the Version 6 library is called IMS Version 7 Command Reference. v IMS Version 7 Utilities Reference: Database and Transaction Manager The books formerly titled IMS/ESA Utilities Reference: Database Manager and IMS/ESA Utilities Reference: Transaction Manager in the Version 6 library have been combined into one book called IMS Version 7 Utilities Reference: Database and Transaction Manager. v IMS Version 7 Application Programming: Database Manager and IMS Version 7 Customization Guide
| | | | | | | | | |
© Copyright IBM Corp. 2000, 2002
xvii
| | |
The chapter titled ″IMS Adapter for REXX Exit Routine″ has been moved from the IMS Version 7 Application Programming: Database Manager to the IMS Version 7 Customization Guide.
| | | |
v IMS Version 7 Sample Operating Procedures For IMS Version 7, this book is available only in BookManager and PDF softcopy on the product kit (LK3T-3526), the OS/390 Collection CD-ROM (SK2T-6700), and on the Web at: http://www.ibm.com/ims
| | |
The library includes a new book: IMS Version 7 IMS Java User’s Guide (IJUG). As a new book, the IJUG is available only in PDF and BookManager softcopy on the product kit (LK3T-3526) and on the Web at: http://www.ibm.com/ims
xviii
IMS Java User’s Guide
| |
Chapter 1. Overview of IMS Java
| | | |
IMS Java application support (hereafter called IMS Java) allows you to write Java application programs that access IMS databases from IMS, WebSphere Application Server for z/OS and OS/390, CICS Transaction Server for z/OS, or DB2 UDB for z/OS and OS/390 Stored Procedures.
| | | | | | |
IMS Java application programs use JDBC or the IMS Java hierarchic database interface. JDBC is the SQL-based standard interface for data access in the Java 2 SDK Standard Edition and Enterprise Edition. IMS Java’s implementation of JDBC supports a selected subset of the full facilities of the JDBC 2.0 API. The IMS Java hierarchic database interface is more closely related to the standard DL/I database call interface used with other languages, and provides a lower-level access to IMS database functions than the JDBC interface.
| | | |
IMS Java provides class libraries that allow you to easily develop applications that can access IMS’s broad range of database types and options, including: v Full function databases v High Availability Large Databases (HALDBs) v Fast Path Data Entry Databases (DEDBs) v Logical relationships v Secondary indexes
| | | | | | |
IMS Java application programs can be message-driven or non-message-driven and can handle a variety of message processing:
| |
v v v v
| |
Regardless of what environment the IMS Java application runs in, it accesses the IMS databases the same way.
| | | | | | | | | | | | | | |
Conversational and non-conversational transactions Multi-segment and single-segment messages Message Formatting Services (MFS) Alternate PCB program switching
Design Process 1. Determine what database information the application needs to process. 2. Create the IMS Java metadata classes based on the PSB using the DLIModel utility. The IMS database administrator, in addition to generating the PSB, also runs the DLIModel utility to create the IMS Java Metadata classes for the Java application developer to use to write the application program. 3. Write the application program. The DLIModel Java Report, generated by the DLIModel utility, provides the information about the IMS database. 4. Configure environment and deploy application.
IMS Environment Overview IMS Java application programs run in one of two IMS dependent regions, which provide a Java Virtual Machine (JVM) environment for the Java applications:
© Copyright IBM Corp. 2000, 2002
1
| | |
v Java Message Processing (JMP) region for message-driven Java applications. JMP applications process input messages from the message queue, similar to Message Processing Programs (MPPs), in a DB/DC environment.
| | | |
v Java Batch Processing (JBP) region for non-message-driven Java applications. JBP applications run in an online batch mode and do not process input messages, similar to non-message-driven Batch Message Processing (BMP) applications, in a DBCTL or a DB/DC environment.
| | |
Restrictions: v IMS Java applications cannot run in an IMS batch environment. v JBPs cannot be message driven.
| | | | |
Related Reading: v For guidance information on designing an IMS application, see IMS Version 7 Application Programming: Design Guide. v For information on configuring JMP and JBP regions, see “IMS Setup” on page 4 and IMS Version 7 Installation Volume 2: System Definition and Tailoring.
| |
WebSphere for z/OS Environment Overview
| | | | |
You can write IMS Java applications that run on a WebSphere Application Server for z/OS and OS/390 J2EE server and access IMS databases. When WebSphere for z/OS and IMS DB are on the same operating system image, the IMS Java application—a WebSphere for z/OS Enterprise Java Bean (EJB)—accesses IMS databases using the Open Database Access (ODBA) interface.
| |
Related Reading: For information on configuring WebSphere for z/OS to run IMS Java applications, see “WebSphere for z/OS Setup” on page 8.
| |
CICS Environment Overview
| |
You can write IMS Java applications that run on CICS Transaction Server for z/OS and access IMS databases.
| | |
Related Reading: v For information on configuring CICS to runs IMS Java applications, see “CICS Setup” on page 13. v For information on developing an IMS Java application that runs on a CICS Transaction Server, see “CICS Applications” on page 59.
| | | |
DB2 Environment Overview
| |
You can write DB2 UDB for z/OS and OS/390 Stored Procedures that access IMS databases.
| | | | |
Related Reading: v For information on configuring DB2 to run IMS Java applications, see “DB2 Setup” on page 15. v For information on developing an IMS Java application that runs as a DB2 stored procedure, see “DB2 Stored Procedures” on page 59.
2
IMS Java User’s Guide
Chapter 2. Setting Up Your Environment for IMS Java | | | | |
How to set up your environment to run an IMS Java application in IMS, WebSphere for z/OS, CICS, and DB2 is discussed in this chapter. The first two sections, “System Requirements for All Environments” and “General Restrictions”, apply to all environments. Environment-specific requirements and restrictions, and configuration and installation verification information is in each environment’s setup section.
| | |
In this chapter: v “System Requirements for All Environments” v “General Restrictions”
| | | | |
v v v v v
| | | | | | | | | | | | | | | | |
“IMS Setup” on page 4 “WebSphere for z/OS Setup” on page 8 “CICS Setup” on page 13 “DB2 Setup” on page 15 “DLIModel Utility Setup” on page 19
System Requirements for All Environments To use IMS Java to write application programs that access IMS databases, the following software is required: v IBM Developer Kit for OS/390, Java 2 Technology Edition with the Persistent Reusable Java Virtual Machine v OS/390 Version 2 Release 10 or higher v UNIX System Services available at runtime v Hierarchic File System (HFS) on operating system (For information on preparing HFS, see OS/390: Unix System Services File System Interface Reference) Related Reading: For systems requirements for specific environments, see: v “IMS System Requirements” on page 4 v “WebSphere for z/OS System Requirements” on page 8 v “CICS System Requirements” on page 13 v “DB2 System Requirements” on page 15
General Restrictions
| |
For all environments, IMS Java supports only the AIB interface; therefore, the database PCBs in your PSBGEN must be explicitly named.
| | | |
An IMS Java application may use path calls to access hierarchic paths of segments. Therefore, your PSBs may need to specify the P processing option for some or all segments. See Chapter 3, “Accessing an IMS Database” on page 23 for more information.
| | |
IMS does not support local transactions. Therefore, the commit, rollback, and setAutoCommit methods on an IMS Java JDBC Connection object are not supported and throw an SQLException.
| |
Related Reading: For restrictions on specific environments, see: v “IMS Restrictions” on page 4 © Copyright IBM Corp. 2000, 2002
3
v “WebSphere for z/OS Restrictions” on page 8 v “CICS Restrictions” on page 13 v “DB2 Restrictions” on page 15
| | | | |
IMS Setup This section describes the system requirements, restrictions, configuration, and installation verification specific to the IMS environment.
| | |
IMS System Requirements Java applications running in an IMS JMP or JBP region do not require any additional system requirements other than the requirements listed in “System Requirements for All Environments” on page 3.
| | | |
IMS Restrictions
|
JMP and JBP applications must be single threaded.
|
JBP applications must be non-message-driven applications.
|
JMP and JBP applications cannot access DB2 databases.
|
“General Restrictions” on page 3 lists other restrictions.
|
IMS Configuration
| |
This section gives the steps to configure JMP and JBP IMS Java dependent regions.
| | | | | | | |
Related Reading: v For detailed information on DFSJBP and DFSJMP procedures, used to start JVM dependent regions, see IMS Version 7 Installation Volume 2: System Definition and Tailoring. v For details about master JVMs and worker JVMs, and for a complete list of possible JVM options, see IBM Developer Kit for OS/390, Java 2 Technology Edition: New IBM Technology featuring Persistent Reusable Java Virtual Machines.
| | |
Configuring a JMP Region
| | | |
JVMOPMAS=member name Required parameter specifies the name of the member in IMS.PROCLIB that contains the JVM options for the master JVM. The master JVM defines the class cache for its associated worker JVMs.
To run IMS Java applications in a JMP region, the region must be initialized with specific JVM options. Specify the following parameters:
| | |
A sample member, called DFSJVMMS (master JVM options member), is supplied in the IMS sample library SDFSISRC. DFSJVMMS contains a subset of the possible JVM options.
|
This master JVM options member must contain the following JVM options:
| | | |
-Dibm.jvm.shareable.application.class.path= Specify the path names to your IMS Java application class files. Separate the path names with a colon and with no spaces. The greater-than symbol (>) acts as a nest-line extension.
4
IMS Java User’s Guide
IMS Setup | |
If your .class files are contained in a .jar file, then the absolute path name to the .jar file includes the .jar extension.
| | | |
-Dibm.jvm.trusted.middleware.class.path= Specify the path name. If using the default IMS java directory, enter /usr/lpp/ims/imsjava71/imsjava.jar. The imsjava.jar file contains the runtime libraries for IMS Java.
| | | | |
JVMOPWKR=member name Optional parameter specifies the name of the member in IMS.PROCLIB that contains the JVM options for the worker JVM. The worker JVM is created in the same address space as its master JVM. It uses the class cache defined by the master JVM.
| | | | | |
There is a sample member, called DFSJVMWK (worker JVM options member), supplied in the IMS sample library. DFSJVMWK contains a subset of the possible JVM options. ENVIRON=member name Required parameter specifies the name of a data set member that is concatenated in the PROCLIB DD.
|
Sample member DFSJVMEV is supplied in the IMS sample library SDFISRC.
| | | |
Specify the LIBPATH= environment variable in DFSJVMEV. There must be no space between the equal sign (=) in LIBPATH= and the beginning of the first path name. LIBPATH= must be set to: v The path name to the libjvm.so and libatoe.so DLLs.
| |
v The path name to the IMS V7.1 Java native C code, libJavTDLI.so. If you are using the default IMS Java directory, enter /usr/lpp/ims/imsjava71.
| | | | | | | | | |
Example: If you code ENVIRON=DFSENV on your JMP or JBP procedure, the DFSENV member must reside in IMS.PROCLIB or its equivalent. It must contain the following (comments are optional): * LIBPATH environment variable * ---------------------------* /u/oeusr02/shiraz24/J1.3/bin/classic is path to libjvm.so * /u/oeusr02/shiraz24/J1.3/bin is path to libatoe.so * /usr/lpp/ims/imsjava71 is path to libJavTDLI.so LIBPATH=/u/oeusr02/shiraz24/J1.3/bin/classic: > /u/oeusr02/shiraz24/J1.3/bin:/usr/lpp/ims/imsjava71
* * * * *
| | | |
Configuring a JBP Region
| | |
JVMOPMAS=member name For details see JVMOPMAS= for the JMP procedure under “Configuring a JMP Region” on page 4.
| | |
ENVIRON=member name For details see ENVIRON= for the JMP procedure under “Configuring a JMP Region” on page 4.
|
PROCLIB member DFSJVMAP: The member name must be DFSJVMAP.
| | |
DFSJVMAP is a member contained in a data set that is concatenated in the PROCLIB DD. A sample member, DFSJVMAP is supplied in the IMS sample library, SDFSISRC.
To run IMS Java applications in a JBP region, initialize the region with the following JVM options. Specifically, the following new procedure parameters are needed to initialize a JBP region:
Chapter 2. Setting Up Your Environment for IMS Java
5
IMS Setup Member DFSJVMAP is optional and is read during dependent region application scheduling, making it a dynamic member. You do not need to shut down IMS when adding application name mappings to DFSJVMAP for the changes to take affect. Member DFSJVMAP maps all of the 8-byte (or less), uppercase IMS Java application names that are specified to IMS to the true OMVS path name for the IMS Java application.class file.
| | | | | | |
IMS Installation Verification To verify that IMS Java is installed properly in an IMS environment: 1. Expand the file samples.tar. For instructions on expanding this file, see the Readme file in the samples directory. 2. Set the following four JVM members in IMS.PROCLIB (created at system generation), as follows: v DFSJVMAP
| | | | | | |
DFSIVP37=samples/ivp/ims/IMSIVP
DFSIVP37 is the PSB name. v DFSJVMEV
| | |
LIBPATH=/usr/lpp/J1.3/bin/classic:/usr/lpp/J1.3/bin:/usr/lpp/ims/imsjava71
/usr/lpp/ims/imsjava71 contains the native library code for IMS Java, such as libJavTDLI.so
| |
v DFSJVMMS
| | | | | | | | | | | | | | | | | | | | | | | |
-Dibm.jvm.shareable.application.class.path=> /usr/lpp/ims/imsjava71/samples.jar -Dibm.jvm.trusted.middleware.class.path=> /usr/lpp/ims/imsjava71/imsjava.jar -Xinitacsh128k -Xinitsh128k -Xmaxf0.6 -Xminf0.3 -Xmx64M -Xoss400k
v DFSJVMWK -Xmaxf0.6 -Xminf0.3 -Xmx64M -Xoss400k
3. Create HFS files JVM.out and JVM.err in the directory. 4. Submit the JCL stream to start a JMP (Java Message Processing) region. The JCL must contain the following: v Four IMS.PROCLIB members defined in step 2 v JAVAOUT and JAVAERR DD statements to allow standard output and standard errors to be sent to a file. For example: //JAVAOUT DD PATH=’/myApplication/JVM.out’ //JAVAERR DD PATH=’/myApplication/JVM.err’
Important: This procedure fails if the HFS files JVM.out and JVM.err do not exist in the specified directory. 5. From the IMS terminal, invoke the formatted screen for the transaction by issuing the following command:
| | | | |
/format IVTCM
6
IMS Java User’s Guide
IMS Setup | | | | | | | | | | | | | | | | | | | | | | | || | | | | | | | | | | | | | | | | | | | | | | | | | | || | | | |
An input screen as shown in Figure 1 is displayed. ************************************************** * IMS INSTALLATION VERIFICATION PROCEDURE * ************************************************** TRANSACTION TYPE : CONVERSATIONAL DATE : 04/03/00 PROCESS LAST FIRST
CODE
(*1) :
NAME
(*1) PROCESS CODE ADD DELETE UPDATE DISPLAY TADD END
:
NAME
:
EXTENSION
NUMBER
:
INTERNAL
ZIP CODE
:
SEGMENT# :
Figure 1. Example of a Blank IMS Installation Verification Procedure Screen
6. Enter DISPLAY for PROCESS CODE and LAST1 for LAST NAME. Figure 2 shows an example for the display query. If IMS Java is properly installed, the output shown in Figure 3 on page 8 is ************************************************** * IMS INSTALLATION VERIFICATION PROCEDURE * ************************************************** TRANSACTION TYPE : CONVERSATIONAL DATE : 04/19/00 PROCESS CODE LAST FIRST
(*1)
NAME NAME
:
DISPLAY
:
LAST1
:
EXTENSION
NUMBER
:
INTERNAL
ZIP CODE
:
(*1) PROCESS CODE ADD DELETE UPDATE DISPLAY TADD END
SEGMENT# : Figure 2. Example IMS Installation Procedure Screen with Transaction Input Information
displayed.
Chapter 2. Setting Up Your Environment for IMS Java
7
WebSphere for z/OS Setup | | | | | | | | | | | | | | | | | | | | | || | | || |
************************************************** * IMS INSTALLATION VERIFICATION PROCEDURE * ************************************************** TRANSACTION TYPE : CONVERSATIONAL DATE : 04/19/00 PROCESS LAST FIRST
CODE
(*1) :
NAME NAME
DISPLAY
:
LAST1
:
FIRST1
EXTENSION
NUMBER
:
8-111-1111
INTERNAL
ZIP CODE
:
D01/R01
Person found!
(*1) PROCESS CODE ADD DELETE UPDATE DISPLAY TADD END
SEGMENT# :
Figure 3. Example IMS Installation Verification Procedure Screen with Transaction Output Information
WebSphere for z/OS Setup
| |
This section assumes you are familiar with WebSphere Application Server for z/OS and OS/390, its Administration application, and its Application Assembly tool.
|
Related Reading:
| | | | | |
v For detailed information about how to use the Administration application, see WebSphere Application Server V4.0.1 for z/OS and OS/390 : System Management User Interface. v For detailed information about assembling and deploying an EJB onto a J2EE server, see WebSphere Application Server V4.0.1 for z/OS and OS/390 : Assembling Java 2 Platform, Enterprise Edition (J2EE) Applications.
|
WebSphere for z/OS System Requirements
| | |
Access to IMS databases from WebSphere applications requires WebSphere Application Server for z/OS and OS/390 V4.0.1 or higher and additional WebSphere Application Server z/OS Connection Management support.
|
“System Requirements for All Environments” on page 3 lists other requirements.
|
WebSphere for z/OS Restrictions The following restrictons apply to WebSphere for z/OS EJBs for accessing IMS databases: v IMS Java does not support container-managed signon or component-managed signon. v The java.sql.Connection object must be acquired, used, and closed within a transaction method.
| | | | | | | | |
v A global transaction must exist before creating a Statement or PreparedStatement object from a JDBC connection. Either specify container-demarcated transactions in the EJB deployment descriptor or explicitly
8
IMS Java User’s Guide
WebSphere for z/OS Setup | | | | | | | | | | | |
begin a global transaction by calling javax.transaction.UserTransaction.begin in the EJB method before creating a Statement or PreparedStatement object. “General Restrictions” on page 3 lists other restrictions.
WebSphere for z/OS Configuration To deploy an EJB on a WebSphere for z/OS J2EE server, you must perform the following steps: 1. Configure the WebSphere for z/OS J2EE server for access to IMS. 2. Configure the WebSphere for z/OS J2EE server to locate the IMS JDBC Resource Adapter. 3. Deploy an instance of the IMS JDBC Resource Adapter. 4. Deploy an Enterprise Archive (EAR) that contains an Enterprise Java Bean (EJB).
| | | | | |
Configuring the WebSphere for z/OS J2EE Server for IMS Access
| | |
To configure WebSphere for z/OS to access IMS databases: 1. Configure and deploy a DRA startup table.
| | |
To run an EJB on a WebSphere for z/OS J2EE server, you must configure WebSphere for z/OS to access IMS databases using ODBA. ODBA uses the database resource adapter (DRA) to access IMS databases. More details about the steps in this section are in IMS Version 7 Installation Volume 2: System Definition and Tailoring.
2. Link DRA startup table into a load library. 3. Update the JCL for the WebSphere for z/OS J2EE server on which the EJB will run by adding the load library that contains the DRA start up table and ODBA runtime code to the STEPLIB.
| | | | | | | |
Configuring the WebSphere for z/OS J2EE Server to Locate the IMS JDBC Resource Adapter
| |
Important: If you do not edit the jvm.properties file correctly, PSB allocation fails when using the IMS JDBC Resource Adapter.
| | | | | | | | | | |
To configure the WebSphere for z/OS J2EE server to locate the IMS JBDC Resource Adapter:
You must configure the WebSphere for z/OS J2EE server for the IMS JDBC Resource Adapter (also referred to as the IMS JDBC Connector). The procedure is described in this section. Activating a conversation sets the sysplex and J2EE properties for the IMS JDBC Resource Adapter. Expanding the custom service file and entering its directory in the file jvm.properties allows WebSphere for z/OS to initialize and terminate ODBA.
1. Create a conversation and define the IMS JDBC Resource Adapter as a J2EE resource: a. Open the WebSphere Application Server for z/OS and OS/390 Administration tool. b. Add a conversation. c. Navigate to the sysplex that will run the EJBs. d. Modify the sysplex properties by selecting Connection Management. e. Modify the J2EE properties by defining the CLASSPATH and LIBPATH environment variables:
Chapter 2. Setting Up Your Environment for IMS Java
9
WebSphere for z/OS Setup v For the CLASSPATH environment variable, enter the full name of the directory that contains the file imsjava.jar, including the file name. If you use the default IMS installation directory, enter /usr/lpp/ims/imsjava71/imsjava.jar v For the LIBPATH environment variable, enter the full name of where IMS Java is installed.
| | | | | | | | | | | | |
If you use the default IMS installation directory, enter /usr/lpp/ims/imsjava71 f. Save and activate the conversation. 2. In the installation directory, expand the file imsjava71.rar. If you used the default directory to install IMS, the file is in /usr/lpp/ims/imsjava71. To expand the file, enter the following command:
| | | |
The expansion puts the following files (in UTF-8 format) in the same directory as the imsjava71.rar file: v IMSJdbcCustomService.xml v howto.html
jar -xvf imsjava71.rar
| | | | | | | | | | | |
Related Reading: For more information about IMS JDBC Resource Adapter configuration, see the howto.html file. Because it is encoded in UTF-8 format, you can not read it in the OS/390 environment. To read the file, expand imsjava71.rar on your desktop. 3. Edit the jvm.properties file for WebSphere J2EE server regions that will access IMS databases to identify the location of the file IMSJdbcCustomService.xml.
| | | | | |
Deploying an Instance of the IMS JDBC Resource Adapter Configuring and deploying an instance of the IMS JDBC Resource Adapter creates a data source for an EJB. Deploy a new instance for each database or database resource adapter (DRA) startup table an EJB accesses. See “Two Strategies for Deploying Instances of IMS JDBC Resource Adaptor” on page 11 for more information on when to deploy a new instance.
| | |
Note: If you are setting up WebSphere for the first time and want to verify your installation, start the procedure in the following section “WebSphere for z/OS Installation Verification” on page 12.
| | | | | | | | | |
To deploy an instance of the IMS JDBC Resource Adapter: 1. Open the WebSphere Application Server for z/OS and OS/390 Administration tool. 2. Add a conversation. 3. Navigate to the sysplex that will run the EJBs.
To edit the jvm.properties file, add the directory where the file IMSJdbcCustomService.xml is to the preconfigured custom services in the jvm.properties file. If you use the default IMS installation directory, enter: com.ibm.websphere.preconfiguredCustomServices= /usr/lpp/ims/imsjava71/IMSJdbcCustomService.xml
The following folders are displayed: J2EEServers Servers Systems J2EE Resources
10
IMS Java User’s Guide
WebSphere for z/OS Setup | | | | | | |
Logical Resource Mapping 4. Add a J2EE resource. The resource name is your choice. The type is IMSJdbcDataSource. 5. Add a J2EE resource instance. The name is your choice. 6. Enter the DRA startup table name and optionally the DLIDatabaseView subclass name. To decide whether to add a DLIDatabaseView subclass name, see “Two Strategies for Deploying Instances of IMS JDBC Resource Adaptor”.
|
7. Save and activate the conversation.
| | | |
Note: These instructions use two conversations to deploy the IMS JDBC Resource Adapter and the Enterprise Archive (EAR). However, you can also deploy an EAR in the same conversation that deploys the IMS JDBC Resource Adapter instance.
| | |
Two Strategies for Deploying Instances of IMS JDBC Resource Adaptor: When configuring an instance of the IMS JDBC Resource Adapter, you can optionally set the DLIDatabaseView subclass name.
| | | |
If you do set the subclass name, you must create a new instance of the IMS JDBC Resource Adapter for every database an EJB accesses. You can override the DLIDatabaseView subclass name (set in step 6) in the DataSource object by calling the setDatabaseView method and providing the fully-qualified name of the subclass.
| | | |
If you do not set the subclass name, you only need to deploy an instance of the IMS JDBC Resource Adapter for each DRA startup table. In the EJB, define the DLIDatabaseView subclass name (set in step 6) in the DataSource object by calling the setDatabaseView method and providing the fully-qualified name of the subclass.
| |
Deploying an EJB onto a WebSphere for z/OS J2EE Server
| | | | | | |
To deploy your application onto the WebSphere for z/OS J2EE server: 1. Package the EJB into an Enterprise Archive (EAR) using a development tool such as Websphere Studio Application Developer Integrated Edition.
| | | | | | | | | | | | | | |
After you develop the EJB, deploy it on the WebSphere for z/OS J2EE server.
2. Import the EAR into WebSphere for z/OS and OS/390 Application Assembly tool. 3. Create a resolved EAR suitable for deploying on a WebSphere for z/OS J2EE server. 4. Open the WebSphere Application Server for z/OS and OS/390 Administration application. 5. Add a conversation. 6. Navigate to the J2EEServers folder of the sysplex that will run the EJB. The following folders are displayed: J2EEServers Servers Systems J2EE Resources Logical Resource Mapping 7. Expand the J2EEServers folder and choose the server to install the EJB on. 8. Install the EJB. a. Specify the fully-qualified directory name of the EAR and the FTP server of the sysplex where the EJB will run. b. Set the JNDI name and path. Chapter 2. Setting Up Your Environment for IMS Java
11
WebSphere for z/OS Setup c. Associate the J2EE resource defined in “Deploying an Instance of the IMS JDBC Resource Adapter” on page 10. 9. Save and activate the conversation.
| | | |
WebSphere for z/OS Installation Verification
| | | | | |
After you have configured WebSphere for z/OS to access IMS (“Configuring the WebSphere for z/OS J2EE Server for IMS Access” on page 9) and to locate the IMS JDBC Resource Adapter (“Configuring the WebSphere for z/OS J2EE Server to Locate the IMS JDBC Resource Adapter” on page 9), you can verify that your systems are configured correctly by running the installation verification program (IVP).
| | | | |
Note: You can also use this procedure to install the dealership sample EAR, which is also in samples.tar. The sample file name is imsjavaDealership.ear and the DLIDatabaseView subclass name is samples.dealership.AUTPSB11DatabaseView. 1. Transfer the IVP EAR file in binary mode to your workstation: a. Expand the samples.tar file. For instructions, see the Readme file in the samples directory. b. Use FTP to transfer the file imsjavaIVP.ear to your workstation. 2. Deploy an instance of the IMS JDBC Resource Adapter: a. Open the WebSphere Application Server for z/OS and OS/390 Administration tool. b. Add a conversation. c. Navigate to the sysplex that will run the EJBs.
| | | | | | | |
The following folders are displayed: J2EEServers Servers Systems J2EE Resources Logical Resource Mapping d. Add a J2EE resource. The resource name is your choice. The type is IMSJdbcDataSource. e. Add a J2EE resource instance with the following information: v J2EE Resource Instance Name: your choice, such as IMSJavaIVPDataSource
| | | | | | | | | | | |
v System Name: name of system that will run the server v DLIDatabaseView subclass name: samples.ivp.DFSIVP37DatabaseView
| |
v DRA Startup Table: name of your DRA table f. Save and activate the conversation. 3. Assemble the IVP EAR: a. Import the EAR into WebSphere for z/OS and OS/390 Application Assembly tool. b. Create a resolved EAR suitable for deploying on a WebSphere for z/OS J2EE server. 4. Deploy the IVP EAR, which contains the IVP JAR file and the IVP Web Archive (WAR): a. Open the WebSphere Application Server for z/OS and OS/390 Administration application. b. Add a conversation.
| | | | | | | | | | |
12
IMS Java User’s Guide
WebSphere for z/OS Setup | | | | | | | | | | | | |
c. Navigate to the J2EEServers folder of the sysplex that will run the EJB. The following folders are displayed: J2EEServers Servers Systems J2EE Resources Logical Resource Mapping d. Expand the J2EEServers folder and choose the server to install the EJB on. e. Install the EJB with the following information: v EAR file name: imsjavaIVP.ear v System name: FTP server for the sysplex that the IVP EJB will run on v JNDI Path: Clear the text field v JNDI Name: samples.ivp.was.WASIVPSessionHome
| | | | | | | | | | | |
v Associate the J2EE resource defined in step 2 on page 12. f. Save and activate the conversation. 5. Update the HTTP server to access the IVP Web application: a. Update the file webcontainer.conf to contain the context root specification for the IVP: host.default_host.contextroot=/,/IMSJdbcIVPWeb,/IMSJdbcIVPWeb/*
b. Update the file httpd.conf to contain the service entry for IVP: Service /IMSJdbcIVPWeb/*
6. Run the IVP to verify the installation: a. Open a Web browser. b. Enter the following Web address, prefaced by the specific host IP address: http://host_IP_address:8080/IMSJdbcIVPWeb/WASIVP.html
| |
CICS Setup
|
CICS System Requirements
| |
To run Java application programs in a CICS environment, you must have CICS Transaction Server for z/OS Version 2.
|
“System Requirements for All Environments” on page 3 lists other requirements.
| | | | | |
CICS Restrictions In a CICS environment, only one PSB can be allocated at a time. Therefore, an application can only have one active JDBC connection at a time. The application must close the JDBC connection before opening another JDBC connection. “General Restrictions” on page 3 lists other restrictions.
CICS Configuration
| |
To configure CICS for IMS Java, modify the CICS JVM profile DFHJVMPR. The default PDS is DFHJVM.
| | |
To configure CICS for IMS Java, modify the following in DFHJVMPR: 1. Include the IMS Java runtime libraries (imsjava.jar) as part of the CICS trusted middleware:
Chapter 2. Setting Up Your Environment for IMS Java
13
CICS Setup | | |
a. Add either a TMPREFIX or TMSUFFIX variable. The TMPREFIX adds the libraries at the head of the middleware path and TMSUFFIX adds the libraries to the end of the middleware path.
|
b. Point to the location of the IMS Java libraries.
| | | | | | | | | | |
For example, if you use the default installation directory, add the following line: TMSUFFIX=/usr/lpp/ims/imsjava71/imsjava.jar
2. Update the LIBPATH variable to contain the location of the IMS Java file libJavTDLI.so. For example, if you use the default installation directory, add the following line: LIBPATH=/usr/lpp/ims/imsjava71
3. Change the HFS dfjjvmpr.props file to set the shareable application classpath (The location of this file is specified via the JVMPROPS variable in the CICS JVM profile). Point this classpath to the locations of the user applications. For example: ibm.jvm.shareable.application.class.path=/imsjava/myApplication
Related Reading: For detailed information on CICS system definition, see CICS Transaction Server for OS/390: CICS System Definition Guide.
| | |
Installation Verification
| | |
After you configure CICS to run IMS Java applications, verify that IMS Java is installed correctly and that CICS is configured correctly to run IMS Java applications.
| | | | |
To verify the installation, install and run the CICS IVP: 1. Set the application classpath to point to samples.jar. Do this in the HFS file, dfsjjvm.props (The location of dfsjjvm.props is specified with the JVMPROPS variable in the CICS JVM profile data set member). 2. Start IMS DBCTL and CICS. 3. Turn off the upper-case translation feature. By default everything you type on the CICS terminal is converted to uppercase. However, the IVP JVM class (with the absolute path) contains lower case letters that must remain in lower case. To turn off this feature: a. On the CICS terminal, enter the transaction code CEOT NOUCTRAN. b. Press F3 to return to main CICS terminal. 4. Define a program that contains the JVM class to be run, which is CICSIVP.
| | | | | | |
a. On the CICS terminal, type CEDA DEFINE PROGRAM b. Fill in only the program name, group name, concurrency, if JVM and the JVM class.
| | | | | | | | | | | | | | |
PROGram Group COncurrency JVM JVMClass
==> cicsivp (or whatever program name you choose) ==> ivp (or whatever group name you choose) ==> Threadsafe ==> Yes ==>samples.ivp.cics.CICSIVP
c. Press F3 to return to main CICS terminal. 5. Define a transaction that can run the program and, in turn, our JVM class (such as CICSIVP). a. On the CICS terminal, type CEDA DEFINE TRANSACTION b. Fill in only the transaction, program (defined above), and group (same as program’s group):
14
IMS Java User’s Guide
CICS Setup TRANSaction ==> civp Group ==> ivp PROGram ==> cicsivp
| | | | | | | | | | | | | | | |
c. Press F3. 6. Install CICSIVP. a. On the CICS terminal, enter CEDA INSTALL b. Fill in only the program and group names: PROGram Group
=> cicsivp => ivp
c. Press F3. 7. Install the transaction civp. a. On the CICS terminal, type CEDA INSTALL b. Fill in only the transaction and group names: TRANSaction => civp Group => ivp
c. Press F3. 8. Run the transaction. a. On the CICS terminal, type civp
| | |
b. Press F3.
| |
If the transaction ran successfully, the program correctly returns a first name, last name, zip code, and extension.
| |
DB2 Setup
|
DB2 System Requirements
| | |
Access to IMS databases from DB2 Stored Procedures requires DB2 UDB for z/OS and OS/390 Version 7 with APARs PQ46673 and PQ50443. You also must have the DB2 for OS/390 and z/OS SQLJ/JDBC driver with APAR PQ48383 installed.
|
“System Requirements for All Environments” on page 3 lists other requirements.
|
DB2 Restrictions
| | | |
In a WLM-managed stored procedure address space configured to run LANGUAGE JAVA stored procedures, a considerable amount of storage is used for the Java Virtual Machine. The NUMTCB parameter must be adjusted accordingly. The recommended NUMTCB is a maximum of 7.
|
“General Restrictions” on page 3 lists other restrictions.
|
DB2 Configuration
|
The stored procedures must be compiled (javac) by JDK 1.3.1.
| | | | | | | | |
The following is an example JCL procedure of a Java WLM-established address space: //V71AWLM1 PROC RGN=0M,APPLENV=application_environt_name, // DB2SSN=your_db2-subsystem-name,NUMTCB=7 //IEFPROC EXEC PGM=DSNX9WLM,REGION=&RGN,TIME=NOLIMIT, // PARM=’&DB2SSN,&NUMTCB,&APPLENV’ //STEPLIB DD DISP=SHR,DSN=CEE.SCEERUN //* DB2 Library // DD DISP=SHR,DSN=yourDB2HLQ.SDSNLOAD Chapter 2. Setting Up Your Environment for IMS Java
15
DB2 Setup | | | | | | | | | | | |
// DD DISP=SHR,DSN=yourDB2HLQ.SDSNLOD2 // DD DISP=SHR,DSN=yourDB2HLQ.RUNLIB.LOAD //* DBRM library // DD DISP=SHR,DSN=yourHLQ.SDSNDBRM //* ODBA Interface //DFSRESLB DD DISP=SHR,DSN=yourHLQ.HRESLIB // DD DISP=SHR,DSN=yourHLQ.TNUC0 //JAVAENV DD DISP=SHR,DSN=yourHLQ.JAVAENV //JSPDEBUG DD SYSOUT=* //CEEDUMP DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSOUT DD SYSOUT=*
| | | | | |
Notes: 1. For general purpose use, the first card could be:
| |
ENVAR Settings for the JAVAENV Data Set
| |
JAVA_HOME= HFS directory where the required JVM is installed
| |
DB2_HOME= HFS directory where the DB2 for OS/390 JDBC/SQLJ driver is installed
| | | |
CLASSPATH= can optionally be specified. If CLASSPATH= is specified, it is the path of HFS directories that is searched for Java class files when the stored procedures definition does not specify a JAR
| |
LIBPATH= HFS directory where libJavTDLI.so resides
| | | |
TMSUFFIX= Full path of HFS directory where imsjava.jar is located. If using the default IMS Java directory, specify:
| | | | |
The JAVAENV data set should have the following attributes:
| | | | | |
For example:
| | | | | |
The following is an example of JCL to define your stored procedure to SYSIBM.SYSROUTINES:
//V71AWLM1 PROC RGN=0M,APPLENV=,DB2SSN=,NUMTCB=
2. The PROC name (V71AWLM) must be defined in the RACF started procedure table 3. Your HLQ.TNUC0 is a data set that contains the DRA start-up table The JAVAENV data set must include the following ENVAR settings:
TMSUFFIX=/usr/lpp/ims/imsjava71/imsjava.jar
Organization Record format Record length Block size .
. . . .
. . . .
. . . .
: : : :
PS VB 1028 6144
ENVAR("CLASSPATH=/imsjava", "DB2_HOME=/usr/lpp/db2/dev710", "JAVA_HOME=/usr/lpp/java/J1.3", "LIBPATH=/usr/lpp/ims/imsjava71", "TMSUFFIX=/usr/lpp/ims/imsjava71/imsjava.jar)
//CREATJSP // // //
16
IMS Java User’s Guide
JOB ,’YOUR NAME’, MSGCLASS=H,TIME=3, USER=SYSADM,PASSWORD=XXXXXXXX, MSGLEVEL=(1)
DB2 Setup | | | | | | | | | | | | | | | | | | | | | | | | | | |
//************************************************************* //* Change xx in the PLAN(DSNTIAxx) to your DB2 Version //* such as 71 or 81 //************************************************************* //CREATJSP EXEC PGM=IKJEFT01,DYNAMNBR=20 //STEPLIB DD DISP=SHR,DSN=DB2HLQ.DSNEXIT // DD DISP=SHR,DSN=DB2HLQ.SDSNLOAD //SYSTSPRT DD SYSOUT=* //SYSTSIN DD * DSN SYSTEM(your_db2_subsystem_name) RUN PROGRAM(DSNTIAD) PLAN(DSNTIAxx) LIB(’DB2HLQ.RUNLIB.LOAD’) PARM(’RC0’) //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * CREATE PROCEDURE yourJavaStoredProcedureName(VARCHAR(20) IN, VARCHAR(1000) OUT) FENCED NO SQL LANGUAGE JAVA DYNAMIC RESULT SET 0 EXTERNAL NAME ’packageName.ClassName.methodEntryName’ PARAMETER STYLE JAVA COLLID DSNJDBC WLM ENVIRONMENT your_WLM_Environment_Name; GRANT EXECUTE ON PROCEDURE yourJavaStoredProcedureName TO PUBLIC;
| | | | | | | | | | | | | | | | | | | | | | |
The following is a sample JCL to delete your stored procedure from SYSIBM.SYSROUTINES:
|
//DELETJSP JOB ,’YOUR NAME’, // MSGCLASS=H,TIME=3,USER=SYSADM,PASSWORD=XXXXXXXX, // MSGLEVEL=(1) //************************************************************* //* Change xx in the PLAN(DSNTIAxx) to your DB2 version, //* such as 71 or 81 //************************************************************** //JOBLIB DD DISP=SHR,DSN=CEE.SCEERUN // DD DISP=SHR,DSN=DB2HLQ.DSNEXIT // DD DISP=SHR,DSN=DB2HLQ.SDSNLOAD //PH061S01 EXEC PGM=IKJEFT01,DYNAMNBR=20 //SYSTSPRT DD SYSOUT=* //SYSTSIN DD * DSN SYSTEM(your_DB2_subsystem_name) RUN PROGRAM(DSNTIAD) PLAN(DSNTIA71) LIB(’DB2HLQ.RUNLIB.LOAD’) PARM(’RC0’) //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * DROP PROCDURE yourJavaStoredProcedureName RESTRICT;
DB2 Installation Verification
| |
The following is sample code of the DB2 Client and DB2 Stored Procedure classes for the DB2 installation verification program.
| |
These classes can be found in the samples.tar file (by default in the /usr/lpp/ims/imsjava71/samples directory).
| | | |
To verify that DB2 is configured correctly and that IMS Java is installed correctly: 1. Set CLASSPATH in JAVAENV data set to samples.jar (default is /usr/lpp/ims/imsjava71/samples.jar) 2. Submit the following JCL to define the stored procedure to DB2: Chapter 2. Setting Up Your Environment for IMS Java
17
DB2 Setup //CREATIVP JOB ,’YOUR NAME’, // MSGCLASS=H,TIME=3, // USER=SYSADM,PASSWORD=XXXXXXXX, // MSGLEVEL=(1) //****************************************************************************** //* Change xx in the PLAN(DSNTIAxx) to your DB2 version //* such as: 71 or 81 //****************************************************************************** //CREATJSP EXEC PGM=IKJEFT01,DYNAMNBR=20 //STEPLIB DD DISP=SHR,DSN=DB2HLQ.DSNEXIT // DD DISP=SHR,DSN=DB2HLQ.SDSNLOAD //SYSTSPRT DD SYSOUT=* //SYSTSIN DD * DSN SYSTEM(DB2_Subsystem_Name) RUN PROGRAM(DSNTIAD) PLAN(DSNTIAxx) LIB(’DB2HLQ.RUNLIB.LOAD’) PARM(’RC0’) //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSIN DD * CREATE PROCEDURE IVPStoredProc(VARCHAR (50) IN, VARCHAR (200) OUT,VARCHAR(500) OUT) FENCED NO SQL LANGUAGE JAVA DYNAMIC RESULT SET 0 EXTERNAL NAME ’samples.ivp.db2.DB2IvpStoredProcedure.execute’ PARAMETER STYLE JAVA COLLID DSNJDBC WLM ENVIRONMENT Your_WLM_Environment_Name; GRANT EXECUTE ON PROCEDURE IVPStoredProc TO PUBLIC;
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
3. Submit the following JCL to create a plan for the client program: //BNDIVPCL JOB ,’YOUR NAME’, // MSGCLASS=H,TIME=3, // USER=SYSADM,PASSWORD=XXXXXXXX, // MSGLEVEL=(1) //********************************************************************* //* Change xx in the PLAN(DSNTEPxx) to your DB2 version //* such as: 71 or 81 //********************************************************************* //BINDCLNT EXEC PGM=IKJEFT01,DYNAMNBR=20 //STEPLIB DD DISP=SHR,DSN=DB2HLQ.DSNEXIT // DD DISP=SHR,DSN=DB2HLQ.SDSNLOAD //DBRMLIB DD DISP=SHR,DSN=DB2HLQ.SDSNDBRM //SYSTSPRT DD SYSOUT=* //SYSPRINT DD SYSOUT=* //SYSUDUMP DD SYSOUT=* //SYSTSIN DD * DSN SYSTEM(DB2ID) BIND PACKAGE (DSNJDBC) MEMBER(DSNJDBC1) ISOLATION(UR) ACTION(REPLACE) VALIDATE(BIND) BIND PACKAGE (DSNJDBC) MEMBER(DSNJDBC2) ISOLATION(CS) ACTION(REPLACE) VALIDATE(BIND) BIND PACKAGE (DSNJDBC) MEMBER(DSNJDBC3) ISOLATION(RS) ACTION(REPLACE) VALIDATE(BIND) BIND PACKAGE (DSNJDBC) MEMBER(DSNJDBC4) ISOLATION(RR) ACTION(REPLACE) VALIDATE(BIND) BIND PLAN(DB2IVPCL) KEEPDYNAMIC(YES) ACTION(REPLACE) PKLIST(DSNJDBC.DSNJDBC1, DSNJDBC.DSNJDBC2, DSNJDBC.DSNJDBC3, DSNJDBC.DSNJDBC4) RUN PROGRAM(DSNTEP2) PLAN(DSNTEPxx) LIB(’DB2HLQ.RUNLIB.LOAD’) END
18
IMS Java User’s Guide
DB2 Setup | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
//SYSIN DD * GRANT EXECUTE ON PLAN DB2IVPCL TO PUBLIC; /* //
4. For USS, create a file named db2sqljjdbc.properties that contains the following: DB2SQLJSSID=yourDB2ID DB2SQLJPLANNAME=DB2IVPCL DB2SQLJATTACHTYPE=RRSAF DB2SQLJDBRMLIB=DB2HLQ.SDSNDBRM
The location of this file is pointed to by the environment variable DB2SQLJPROPERTIES. 5. Set environment variables in USS. For example: export SQLJ_HOME=location of your SQLJ driver (for example /usr/lpp/db2/db2710) export JDBC_HOME=location of your JDBC driver (for example /usr/lpp/db2/db2710) export JAVA_HOME=location of your JDK1.3 (for example /usr/lpp/java/J1.3) export DB2SQLJPROPERTIES=/imsjava/jdbclinks/db2sqljjdbc.properties export export export export export
CLASSPATH=$JDBC_HOME/classes/db2jdbcclasses.zip CLASSPATH=$CLASSPATH:$SQLJ_HOME/classes/db2sqljruntime.zip CLASSPATH=$CLASSPATH:$SQLJ_HOME/classes/db2sqljclasses.zip CLASSPATH=$CLASSPATH:/usr/lpp/ims/imsjava71/imsjava.jar CLASSPATH=$CLASSPATH:$JAVA_HOME/lib:.
export LIBPATH=$SQLJ_HOME/lib:$JDBC_HOME/lib export LIBPATH=:$JAVA_HOME/lib:$LIBPATH export LD_LIBRARY_PATH=.:$SQLJ_HOME/bin:$JDBC_HOME/lib export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$JAVA_HOME/lib export PATH=$SQLJ_HOME/bin:$PATH export STEPLIB=yourDB2HLQ.DSNEXIT:yourDB2HLQ.SDSNLOAD: export STEPLIB=yourDB2HLQ.SDSNLOD2:yourDB2HLQ.SDSNLINK:$STEPLIB
6. Issue the following command at the USS prompt while you are in /usr/lpp/ims/imsjava71: java samples.ivp.db2.DB2IvpClient yourDRAname
If the program ran sucessfully, it will display a first name, last name, extension, and zip code.
DLIModel Utility Setup Before the DLIModel utility can be run, from the MVS USS prompt or by running JCL, some preparation is required. Since DLIModel is a Java application, this preparation depends on the Java environment in your installation. Guidelines are provided here, but they may require modification in order to fit your environment.
Preparing the DLIMODEL MVS Procedure The DLIMODEL procedure is delivered as member DFSMODEL in the IMS distribution library SDFSISRC. To prepare this procedure, perform the following steps: 1. Decide how you want to make the required .jar files available to the procedure. The procedure needs the following .jar files (found in the distribution directory /usr/lpp/ims/imsjava71/dlimodel): dlimodel.jar Chapter 2. Setting Up Your Environment for IMS Java
19
DLIModel Utility Setup mofrt.jar xerces.jar ctccobol.jar tdlang.jar
| | | | | | |
The recommended way is to include the files in the appropriate CLASSPATH environment variable for the utility’s runtime environment before running the procedure.
| | | | | | |
If you do not want to change the CLASSPATH environment variable, you can use the -cp option of the java command in step 5 2. Copy the member DFSMODEL from its distribution library SDFSISRC to the PROCLIB from where your installation submits IMS procedures for batch execution. 3. Rename the procedure, if desired. This book assumes that you have renamed it DLIMODEL.
| | | | | | |
4. Determine if you need to create a script file. The script file is an HFS file with a single-line Java command that runs the DLIModel utility (a Java application). The file is referenced in the PARM field in the EXEC statement. You need a script file if the command—including the path and file name of the control data set—exceeds the 100-byte limit. You do not need a script file if you do not exceed the limit and if you tailor the procedure by placing the java command directly in the PARM field.
| | |
5. If needed, create an HFS script file with the java command. (If you do not need the script file, use the same syntax as follows for the command in the PARM field.) In the HFS script file, write a single-line command using the following syntax:
|
(1)
| QQ java
(2) com.ibm.ims.metagen.DLIModel
“$1”
PDS
QT
| |
Notes:
| | |
1
The simple form assumes that the java command is accessible through your PATH envirnoment variable and that the CLASSPATH environment variable includes all necessary .jar files.
| |
2
The $ symbol can vary by locale, so you use the valid value for your USS setup.
| |
com.ibm.ims.metagen.DLIModel Main class of this DLIModel utility.
| | | | |
″$1″ Symbolic parameter that takes the value of the data set name of the utility control statement data set. This symbolic parameter is set from the DSNAME parameter in the EXEC statement that runs the DLIMODEL procedure.
| |
PDS Required parameter is a string literal.
| | | |
If your environment variables are not set as described previously (for example, you are running the utility on an experimental or trial basis), you can use the following syntax for the command (the single line command has been wrapped to fit the page):
20
IMS Java User’s Guide
DLIModel Utility Setup | | |
/path/java -cp /path/dlimodel.jar: /path/mofrt.jar:/path/xerces.jar:/path/ctccobol.jar: /path/tdlang.jar com.ibm.ims.metagen.DLIModel "$1" PDS
| |
/path/java Identifies the JDK 1.3 java command through an explicit path.
| | | |
-cp /path/dlimodel.jar:/path/mofrt.jar:/path/xerces.jar: /path/ctccobol.jar:/path/tdlang.jar Provides a classpath environment for this Java execution. It contains the .jar files required by the utility.
| | | | | | |
Related Reading: For more information about the MVS BPXBATCH utility, see OS/390: Unix Systems Services User’s Guide and OS/390: Unix Systems Services Command Reference. 6. If you used a script file, reference the file in the PARM field of the EXEC statement in the DLIMODEL procedure. As provided, the PARM field references /usr/lpp/ims/imsjava71/dlimodel/go.
Preparing to Run From the MVS USS Prompt
| | | | | | | | | | | |
To run the DLIModel utility from the MVS USS prompt, perform the following steps: 1. Ensure that the following required execution-time .jar files are present in the CLASSPATH environment variable of your shell: dlimodel.jar mofrt.jar xerces.jar ctccobol.jar tdlang.jar 2. Ensure that your PATH environment variable is set so that the JDK 1.3 ″java″ command is accessible. 3. Issue the simple form of the command in the step 5 on page 20 in the previous section.
| |
Alternately, you can add a path prefix to the java command and use the -cp option of the java command, as described in step 5 on page 20 in the previous section.
Chapter 2. Setting Up Your Environment for IMS Java
21
DLIModel Utility Setup
22
IMS Java User’s Guide
| |
Chapter 3. Accessing an IMS Database
|
IMS Java supports two styles of database programming:
| | | |
JDBC JDBC is the SQL-based standard interface for data access in the Java 2 SDK Standard Edition and Enterprise Edition. IMS Java’s implementation of JDBC supports a selected subset of the full facilities of the JDBC 2.0 API. This is the recommended style where sufficient for the application.
| | | | | | | |
IMS Java hierarchic database interface The IMS Java hierarchic database interface is more closely related to the standard DL/I database call interface used with other languages, and provides a lower-level access to IMS database functions than the JDBC interface. Using this style of programming, you can build segment search arguments (SSAs) and call the functions of the DLIConnection object to read, insert, update, or delete segments. With this style, the application has full control to navigate the segment hierarchy.
| | |
Note: Both styles require that you first describe your IMS databases to the IMS Java classes through a metadata class, as described below under “Describing Your IMS Databases to IMS Java” on page 24.
| |
Recommendation: Before accessing an IMS database, you should have a basic understanding of hierarchical databases.
| | |
This chapter uses the sample applications shipped with IMS Java to show how to access IMS database. For information on expanding and locating these files, see the Readme file in the samples directory.
| | | | |
All samples use a car dealership example and use JDBC for database processing. All samples process a common set of databases, and the jobs to define and load these databases are contained in the directory samples/dealership/databases. For information on how to run the database definition and load jobs, see the IMS sample Readme file in the directory samples/dealership/ims/Readme.
| | |
Related Reading: For a full specification of the classes used in this chapter, see the JavaDoc shipped with IMS Java. If using the default installation directory, the JavaDoc is in directory usr/lpp/ims/imsjava71/docs/.
| |
Introduction to the Example Environment
| | | | | |
In this chapter and in Chapter 4, “Writing a Java Application Program” on page 45, a sample application program is introduced. The sample program uses an automobile dealership program for illustration purposes. This and other automobile dealership applications are available in the samples.tar file shipped with the IMS Java product (See the Readme file in the samples directory for instructions on how to expand and access these sample applications).
| | | | | | |
The sample database contains five segment types. The root segment is the Dealer segment. Its child segment is the Model segment. Under the Model segment are its children: the segments Order, Stock, and Sales. This is the same database example that will be used in Chapter 3, “Accessing an IMS Database”, and in “Example 4. Example with Multiple Control Statements” on page 85. See Figure 6 on page 25 for the DBD of this database.
© Copyright IBM Corp. 2000, 2002
23
|
| | | | |
Figure 4. Example Database Hierarchy
The Dealer segment identifies a dealer selling cars. The segment contains a unique dealer number, dealer name and address, and annual sales information.
| | |
Dealers carry car types, each of which has a corresponding Model segment. A Model segment contains a unique type code, descriptive information about the car, and its price.
| | | | |
There is an Order segment for each car ordered for the dealership. The segment is sequenced by an order number that contains information about the options, pricing, order date, and the customer who ordered the car. When a car is delivered to fill a particular order, its serial number and delivery date are added to the segment. The segment is deleted when the customer (or dealer) accepts the car.
| | | | |
A Stock segment is created for each car that is available for sale in the dealer’s inventory. The segment is sequenced by a serial number that is unique to a given model. It contains descriptive information about the car and the date it was delivered to the dealer. The segment remains in the database until the car is sold from stock.
| | |
Finally, when the car is sold, a Sales segment is created. This segment is sequenced by sale date and contains information about the car sold and the purchaser.
| |
JDBC Access Method
|
Describing Your IMS Databases to IMS Java
| | | |
Processing a set of IMS databases by an IMS Java application using JDBC requires that you describe to IMS Java the database view of your application’s PSB. You do this by providing the name of a metadata class when establishing the JDBC database connection.
| | | | |
There are two ways you can prepare the metadata class for a PSB: v Provide the application PSB source and any related DBD source to the DLIModel utility, and specify the generation of the IMS Java metadata class. This is the recommended technique and is described in Chapter 5, “DLIModel Utility” on page 61.
24
IMS Java User’s Guide
JDBC Access Method | |
v Code the metadata class manually. This is described in Appendix A, “Manually Creating IMS Java Metadata Classes” on page 99.
| |
This chapter assumes that you have prepared a metadata class by using the DLIModel utility.
| | | | | | | | | | | | |
The examples used for the rest of this chapter are based on the following simple application. The PSB for the application is as shown in Figure 5. This database is the Automobile Dealership database that was introduced in “Introduction to the Example Environment” on page 23.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
DLR_PCB1 PCB TYPE=DB,DBDNAME=DEALERDB,PROCOPT=GO,KEYLEN=42 SENSEG NAME=DEALER,PARENT=0 SENSEG NAME=MODEL,PARENT=DEALER SENSEG NAME=ORDER,PARENT=MODEL SENSEG NAME=SALES,PARENT=MODEL SENSEG NAME=STOCK,PARENT=MODEL PSBGEN PSBNAME=DLR_PSB,MAXQ=200 END
Figure 5. Example PSB Definition
The physical DBD referenced by this PSB is shown in Figure 6. DBD NAME=DEALERDB,ACCESS=(HDAM,OSAM),RMNAME=(DFSHDC40.1.10) SEGM NAME=DEALER,PARENT=0,BYTES=94, FIELD NAME=(DLRNO,SEQ,U),BYTES=4,START=1,TYPE=C FIELD NAME=DLRNAME,BYTES=30,START=5,TYPE=C SEGM NAME=MODEL,PARENT=DEALER,BYTES=43 FIELD NAME=(MODTYPE,SEQ,U),BYTES=2,START=1,TYPE=C FIELD NAME=MAKE,BYTES=10,START=3,TYPE=C FIELD NAME=MODEL,BYTES=10,START=13,TYPE=C FIELD NAME=YEAR,BYTES=4,START=23,TYPE=C FIELD NAME=MSRP,BYTES=5,START=27,TYPE=P SEGM NAME=ORDER,PARENT=MODEL,BYTES=127 FIELD NAME=(ORDNBR,SEQ,U),BYTES=6,START=1,TYPE=C FIELD NAME=LASTNME,BYTES=25,START=50,TYPE=C FIELD NAME=FIRSTNME,BYTES=25,START=75,TYPE=C SEGM NAME=SALES,PARENT=MODEL,BYTES=113 FIELD NAME=(SALDATE,SEQ,U),BYTES=8,START=1,TYPE=C FIELD NAME=LASTNME,BYTES=25,START=9,TYPE=C FIELD NAME=FIRSTNME,BYTES=25,START=34,TYPE=C FIELD NAME=STKVIN,BYTES=20,START=94,TYPE=C SEGM NAME=STOCK,PARENT=MODEL,BYTES=62 FIELD NAME=(STKVIN,SEQ,U),BYTES=20,START=1,TYPE=C FIELD NAME=COLOR,BYTES=10,START=37,TYPE=C FIELD NAME=PRICE,BYTES=5,START=47,TYPE=C FIELD NAME=LOT,BYTES=10,START=52,TYPE=C DBDGEN FINISH END
Figure 6. DBD Sample Definition
The DLIModel utility produces a DLIModel Java Report of its generated metadata structure. For an example of the report produced by DLIModel see Figure 7 on page 26.
Chapter 3. Accessing an IMS Database
25
JDBC Access Method | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
DLIModel Java Report ======================== Class: DealerDatabaseView in package: com.ibm.ims.tooling generated for PSB: DLR_PSB ================================================== PCB: DealershipDB ================================================== Segment: DEALER Field: DealerNumber Type=CHAR Start=1 Length=4 ++ Primary Key Field ++ Field: DealerName Type=CHAR Start=5 Length=30 Field: DealerAddress Type=CHAR Start=35 Length=50 Field: YTDSales Type=PACKEDDECIMAL Type Qualifier=S9(18) Start=85 Length=10 ================================================== Segment: MODEL Field: ModelTypeCode Type=CHAR Start=1 Length=2 ++ Primary Key Field ++ Field: CarMake Type=CHAR Start=3 Length=10 (Search Field) Field: CarModel Type=CHAR Start=13 Length=10 (Search Field) Field: CarYear Type=CHAR Start=23 Length=4 (Search Field) Field: Price Type=CHAR Start=27 Length=5 (Search Field) Field: EPACityMilage Type=CHAR Start=32 Length=4 Field: EPAHighwayMilage Type=CHAR Start=36 Length=4 Field: Horsepower Type=CHAR Start=40 Length=4 ================================================== Segment: ORDER Field: OrderNumber Type=CHAR Start=1 Length=6 ++ Primary Key Field ++ Field: PurchaserLastName Type=CHAR Start=50 Length=25 (Search Field) Field: PurchaserFirstName Type=CHAR Start=75 Length=25 (Search Field) Field: Options Type=CHAR Start=7 Length=30 Field: Price Type=ZONEDDECIMAL Type Qualifier=99999 Start=37 Length=5 Field: OrderDate Type=CHAR Start=42 Length=8 Field: SerialNo Type=CHAR Start=100 Length=8 Field: DeliverDate Type=CHAR Start=120 Length=8 ================================================== Segment: SALES Field: DateSold Type=CHAR Start=1 Length=8 ++ Primary Key Field ++ Field: PurchaserLastName Type=CHAR Start=9 Length=25 (Search Field) Field: PurchasetFirstName Type=CHAR Start=34 Length=25 (Search Field) Field: StockVINumber Type=CHAR Start=94 Length=20 (Search Field) Field: PurchaserAddress Type=CHAR Start=59 Length=25 Field: SoldBy Type=CHAR Start=84 Length=10 ================================================== Segment: STOCK Field: StockVINumber Type=CHAR Start=1 Length=20 ++ Primary Key Field ++ Field: Color Type=CHAR Start=37 Length=10 (Search Field) Field: Price Type=ZONEDDECIMAL Type Qualifier=99999 Start=47 Length=5 Field: Lot Type=CHAR Start=53 Length=10 (Search Field) Field: DateIn Type=CHAR Start=21 Length=8 Field: DateOut Type=CHAR Start=29 Length=8
| | Figure 7. The IMS Java Summary Report | The DLIModel Summary Report provides you with the following information: | v The name of the metadata class (DealerDatabaseView), to use when you | establish a connection to the database. | v The hierarchy of segments in each PCB view. | v The fields within each segment. These will include the fields specified in the | DBD, but also include additional fields specified to DLIModel based (for example) | on field layouts of segments in existing applications. For example, the fields | DealerAddress and YTDSales in the Dealer segment are added fields. | v The names of PCBs, segments, and fields to use in your JDBC calls. These | names may be alias names assigned to the IMS entities. Alias names are | intended to be more representative and intuitive identifiers for your Java |
26
IMS Java User’s Guide
JDBC Access Method | | | | | | | | | | | | | | | |
application to use rather than the 8-character names in the IMS PSBs and DBDs. In the example the name, DealershipDB replaces the PCB name DLR_PCB1 from the PSB. And a comparison of the names of the segments and the fields in the report with their names in the DBD shows that they have all been assigned more meaningful names. v Data types of fields. The data types of the fields are also based on information supplied to the utility, and supplement the simple TYPE property of fields in the DBD. For example, the field YTDSales in Dealer is described as type PACKEDDECIMAL with a Type Qualifier (format descriptor) of S9(18). v Fields in each segment, identified as primary or secondary index fields, search fields, or other fields. Generally, predicates in WHERE clauses that are based on index fields provide the fastest response. However, predicates may be qualified on search fields if necessary. Predicates may not be qualified on other fields. For example, in segment, Dealer, a search predicate is best qualified on DealerNumber, may be qualified on DealerName if desired, but may not be qualified on DealerAddress or YTDsales.
| | | |
The report is intended to be a sufficient source of information on your data for you to code JDBC calls and write your application. It should not be necessary for you to refer to the generated metadata class, nor to examine the original PSB and DBD source files.
| |
Related Reading: For details of the DLIModel Java Report and its contents, see “DLIModel Java Report” on page 64.
|
Using JDBC to Access an IMS Database
|
This section discusses accessing IMS databases using JDBC.
| | | | | | | | |
Classes and Field Names A database segment definition defines the fields for a set of segment instances similar to the way a relational table defines columns for a set of rows in a table. In this regard, segments relate to tables, and fields in a segment relate to columns in a table as illustrated in Figure 8 on page 28 Similarly, an instance of a segment in a database corresponds to a row (or tuple) in a table. Note that if a segment does not have a unique key the corresponding relational table should be viewed as having a generated unique key added to its column (field) list.
Chapter 3. Accessing an IMS Database
27
JDBC Access Method |
| | | | | | | | |
Figure 8. IMS DB Segments and Fields with Their Corresponding DB2 Tables and Columns
For the purpose of writing JDBC calls, a database segment definition defines the fields for a set of segment instances similar to the way a relational table defines columns for a set of rows in a table. In this way, segments relate to tables, and fields in a segment relate to columns in a table. And so, the name of an IMS segment from the summary report becomes the table name in an SQL query, and the name of a field becomes the column name in the query.
| | |
For example, in the query below, Model is a segment name that is used as a table name in the query:
| | |
In the following example, ModelTypeCode is the name of a field contained in the Model segment and it is used in the SQL query as a column name:
| | | | | |
In both of the preceding examples, Model and ModelTypeCode are alias names assigned by using the DLIModel utility. These names will likely not be the same eight character names used in the database definition for IMS. Alias names are described in further detail in Chapter 5, “DLIModel Utility” on page 61 and aliases simply act as references to the eight character names described in the IMS DBD (database definition).
| | | | | | |
PCB-Qualifying SQL Queries
SELECT * FROM Model
SELECT * FROM Model WHERE ModelTypeCode = ’K1’
In IMS Java Connections are made to PSBs. Therefore, there must be a way to specify which PCB to use when executing an SQL query on the Connection. To do this, segments referenced in the FROM clause of an SQL statement should always be PCB qualified. The one exception to this rule is if the PSB contains only one PCB, in which case the PCB name can be omitted. Here is an example:
28
IMS Java User’s Guide
JDBC Access Method | SELECT * | FROM DealershipDB.Model | | Figure 9. PCB-Qualifying SQL Query Example
|
Recommendation: For coding clarity and performance reasons, segments in the FROM clause should always be PCB qualified, even when not required (unless readability is seriously sacrificed).
Writing an Application that Uses JDBC To use JDBC to read, update, insert, and delete segment instances, an application must: 1. Load the DLIDriver and retrieve a Connection object from the DriverManager. This step is highlighted in bold text in Figure 10 on page 30. 2. Retrieve a Statement or PreparedStatement object from the Connection and execute it. For an example, see “SELECT” on page 35. 3. Iterate the ResultSet returned from the Statement or PreparedStatement object to retrieve specific field results. For an example, see “SELECT” on page 35. Figure 10 on page 30 builds on the sample program described in “Building an IMS Java Application by Example” on page 46, starting from step 1 above. | | | | |
To use abbreviated class names (instead of fully-qualified names) in your program, include import statements at the top of the Java file. Use the following import statement to make IMS database access classes available by their unqualified class names: import com.ibm.ims.db.*;
| | |
Use the following import statement to make JDBC classes available by their unqualified class names:
| | |
When using JDBC to access an IMS database, an application programmer provides the name of the DLIDatabaseView subclass when getting a JDBC Connection object.
| | |
When the following line from Figure 10 on page 30 is executed, DLIDriver, a class in com.ibm.ims.db, registers itself with the JDBC DriverManager:
| | | | |
When the following line from Figure 10 on page 30 is executed, the JDBC DriverManager determines which of the registered drivers supports the supplied string.
| | |
In this case, because the supplied string begins with jdbc:dli:, JDBC DriverManager locates the DLIDriver instance and requests that it create a connection.
import java.sql.*;
Class.forName("com.ibm.ims.db.DLIDriver");
connection = DriverManager.getConnection ("jdbc:dli:dealership.application.DealerDatabaseView");
Chapter 3. Accessing an IMS Database
29
JDBC Access Method package dealership.application; import com.ibm.ims.base.*; import com.ibm.ims.application.*; import com.ibm.ims.db.*; import java.sql.*;
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
public class IMSAuto extends IMSApplication { IMSMessageQueue messageQueue = null; InputMessage inputMessage = null; ModelOutput modelOutput = null; Connection connection = null; public IMSAuto() { super(); } public static void main(String args[]){ IMSAuto imsauto = new IMSAuto(); imsauto.begin(); } public void doBegin() throws IMSException { messageQueue = new IMSMessageQueue(); inputMessage = new InputMessage(); modelOutput = new ModelOutput(); try { Class.forName("com.ibm.ims.db.DLIDriver"); connection = DriverManager.getConnection ("jdbc:dli:dealership.application.DealerDatabaseView"); } catch (Exception e){ reply("Connection not established"); } while(messageQueue.getUniqueMessage(inputMessage)) { if (!inputMessage.getString("ModelTypeCode").trim().equals("")){ if (getModelDetails(inputMessage, modelOutput)) messageQueue.insertMessage(modelOutput); } else { reply("Invalid Input"); }
}
}
| | | | | |
}
IMSTransaction.getTransaction().commit();
public void reply(String errmsg) throws IMSException{ ErrorMessage errorMessage = new ErrorMessage(); errorMessage.setString("MessageText",errmsg); messageQueue.insertMessage(errorMessage); }
Figure 10. JDBC Application
The following list describes the JDBC 2.1 required interfaces that are implemented in the database package, including limitations in the DL/I implementation of these interfaces. java.sql.Connection java.sql.Connection is an object that represents the connection to the
| |
30
IMS Java User’s Guide
JDBC Access Method | | | | |
database. A Connection reference is retrieved from the DriverManager object implemented in the java.sql package. The DriverManager obtains a Connection reference by querying its list of registered Driver instances until it finds one that supports the universal resource locator (URL) passed to DriverManager.getConnection.
| | | |
Restriction: IMS does not support the local, connection-based commit scope defined in the JDBC model. Therefore, the DL/I implementation of Connection.commit, Connection.rollback, and Connection.setAutoCommit results in an SQLException when called from a client program.
| | | |
Figure 11 illustrates the code to establish a connection to the database:
| | | | | | | | | | | | | | |
connection = DriverManager.getConnection ("jdbc:dli:dealership.application.DealerDatabaseView");
Figure 11. Establish a Database Connection
java.sql.DatabaseMetaData DatabaseMetaData defines a set of methods to query information about the database, including capabilities the database might or might not support. The class is provided for tool developers and is normally not used in client programs. Much of the functionality is specific to relational databases and is not implemented for DL/I databases. java.sql.Driver The Driver interface itself is not usually used in client programs, although an application needs to dynamically load a particular Driver implementation by name. One of the first lines in an IMS JDBC program for DL/I access must be: Class.forName("com.ibm.ims.db.DLIDriver");
| | | | | |
This code loads the Driver and causes the Driver implementation to register itself with the DriverManager so that the driver can later be found by DriverManager.getConnection. The Driver implementation creates and returns a Connection object to the DriverManager. The DL/I implementation of JDBC is not fully JDBC compliant and the Driver member jdbcCompliant returns false.
| | | | | |
java.sql.Statement A Statement interface is returned from Connection.createStatement. The Statement and its subclass PreparedStatement define the interfaces that accept SQL statements and return tables as ResultSet objects. The code to create a statement is as follows:
| | | | | | | |
Statement statement = connection.createStatement();
Restriction: The DL/I implementation of Statement does not support: v Named cursors, therefore the method Statement.setCursorName throws an SQLException. v Aborting a DL/I operation, therefore Statement.cancel throws an SQLException. v Setting a time-out for DL/I operations, therefore Statement.setQueryTimeout and Statement.getQueryTimeout throw an SQLException.
Chapter 3. Accessing an IMS Database
31
JDBC Access Method | | | | | | |
java.sql.ResultSet The ResultSet interface defines an iteration mechanism to retrieve the data in rows of a table, and to convert the data from the type defined in the database to the type required in the application. For example, ResultSet.getString converts an integer or decimal data type to an instance of a Java String. The code to return ResultSet is as follows:
| | |
Rather than building a complete set of results after a query is run, the DL/I implementation of ResultSet retrieves a new segment occurrence each time ResultSet.next is called.
| | | | | | |
Restriction: The DL/I implementation of ResultSet does not support: v Returning data as an ASCII stream, therefore ResultSet.getAsciiStream throws an SQLException. v Named cursors, therefore ResultSet.getCursorName throws an SQLException. v The method ResultSet.getUnicodeStream, which is deprecated in JDBC 2.0.
| | | |
java.sql.ResultSetMetaData This interface defines methods to provide information about the types and properties in a ResultSet object. It includes methods such as getColumnCount, isSigned, getPrecision, and getColumnName.
| | | | |
java.sql.PreparedStatement The PreparedStatement interface extends the Statement interface, adding support for pre-compiling an SQL statement (the SQL statement is provided at construction instead of execution) and for substituting values in the SQL statement (UPDATE Suppliers SET Status = ? WHERE City = ?).
|
ResultSet results = statement.executeQuery(queryString);
Supported Data Types in IMS Java
| |
IMS Java supports the following JDBC types. The DLIModel Summary Report indicates the JDBC type that was assigned to each field in your database view.
|
Table 1. Supported Data Types
|
JDBC Type
Java Type
|
CHAR
String
|
VARCHAR
String
|
BIT
boolean
|
TINYINT
byte
|
SMALLINT
short
|
INTEGER
int
|
BIGINT
long
|
FLOAT
float
|
DOUBLE
double
|
BINARY
byte[]
|
PACKEDDECIMAL
java.math.BigDecimal
|
ZONEDECIMAL
java.math.BigDecimal
|
DATE
java.sql.Date
|
TIME
java.sql.Time
32
IMS Java User’s Guide
JDBC Access Method |
Table 1. Supported Data Types (continued)
|
JDBC Type
Java Type
| |
TIMESTAMP
java.sql.Timestamp
| |
The following table shows the available get methods for accessing data of a certain JDBC type.
| | | | |
The methods that are marked with “X” are methods designed for accessing the given data type. No truncation or data loss occurs using those methods. The methods that are marked with “O” are all other legal calls; however, data integrity cannot be ensured using those methods. If the box is empty (it contains neither an “X” nor an “O”), using that method for that data type will result in an exception.
|
Table 2. ResultSet.getxxx Methods to Retrieve JDBC Types
|
BIGINT
FLOAT
DOUBLE
BIT
CHAR
VARCHAR
PACKEDDECIMAL
ZONEDECIMAL
X
O
O
O
O
O
O
O
O
O
O
|
getShort
O
X
O
O
O
O
O
O
O
O
O
|
getInt
O
O
X
O
O
O
O
O
O
O
O
|
getLong
O
O
O
X
O
O
O
O
O
O
O
|
getFloat
O
O
O
O
X
O
O
O
O
O
O
|
getDouble
O
O
O
O
O
X
O
O
O
O
O
|
getBoolean
O
O
O
O
O
O
X
O
O
O
O
|
getString
O
O
O
O
O
O
O
X
X
O
O
|
getBigDecimal
O
O
O
O
O
O
O
O
O
X
X
|
getBytes
|
getDate
O
O
|
getTime
O
O
| |
getTimestamp
O
O
| |
Note: PACKEDDECIMAL and ZONEDDECIMAL are IMS Java JDBC types. All others are standard SQL types defined in SQL92.
| | |
Restriction: PackedDecimal and ZoneDecimal data types do not support the Sign Leading or Sign Separate modes. Sign information is always stored with the Sign Trailing method.
| | | |
TIMESTAMP
INTEGER
getByte
TIME
SMALLINT
|
DATE
ResultSet.getxxx Methods
BINARY
| |
TINYINT
JDBC Types
O
O
O
O
X X
O
O X
O
O
X
General Mappings from COBOL Copybook Types to IMS Java and Java Data Types Table 3 on page 34 describes how COBOL copybook types are mapped to DLITypeInfo constants and Java data types.
Chapter 3. Accessing an IMS Database
33
JDBC Access Method |
Table 3. Mapping from COBOL to IMS and Java
|
CopyBook Format
DLITypeInfo Constant
Java Type
|
PIC X
CHAR
java.lang.String
1
2
|
PIC 9 BINARY
(see Table 4)
(see Table 4)2
|
COMP-1
FLOAT
float
|
COMP-2
DOUBLE
double
PACKEDDECIMAL
java.math.BigDecimal
ZONEDDECIMAL
java.math.BigDecimal
3
|
PIC 9 COMP-3
4
| |
PIC 9 DISPLAY
| | | | | | | |
Notes: 1. Synonyms for BINARY data items are COMP and COMP-4. 2. For BINARY data items, the DLITypeInfo constant and Java type depend on the number of digits in the PICTURE clause. Table 4 describes the type based on PICTURE clause length. 3. PACKED-DECIMAL is a synonym for COMP-3. 4. If the USAGE clause is not specified at either the group or elementary level, it is assumed to be specified as DISPLAY.
|
Table 4. DLITypeInfo Constants and Java Types based on PICTURE clause
| |
Digits in PICTURE clause
Storage Occupied
DLITypeInfo Constant
Java Type
|
1 through 4
2 bytes
SMALLINT
short
|
5 through 9
4 bytes
INTEGER
int
| |
10 through 18
8 bytes
BIGINT
long
| |
Table 5 shows examples of specific CopyBook formats mapped to DLITypeInfo constants.
|
Table 5. CopyBook Formats Mapped to IMS Java Types
|
CopyBook Format
DLITypeInfo Constant
|
PIC X(25)
CHAR
|
PIC S9(04) COMP
SMALLINT
|
PIC S9(06) COMP-4
INTEGER
|
PIC S9(12) BINARY
BIGINT
|
COMP-1
FLOAT
|
COMP-2
DOUBLE
|
PIC S9(06)V99
ZONEDDECIMAL
|
PIC 9(06).99
ZONEDDECIMAL
| |
PIC S9(06)V99 COMP-3
PACKEDDECIMAL
| |
Supported SQL Grammar The following SQL keywords are currently supported in IMS Java. All keywords are case insensitive. SELECT FROM WHERE
| | | | |
34
IMS Java User’s Guide
SQL Grammar INSERT DELETE UPDATE ALL AND DISINCT INTO OR
| | | | | | | |
Restriction: IMS Java does not support aggregate keywords .
| |
SELECT
| | | | |
A SELECT statement is a query used as a top-level SQL statement. A SELECT statement can be executed against a Statement or PreparedStatement object that returns the results as a ResultSet object. Figure 12 on page 36 shows sample code that uses the results of a SELECT query to update modelOutput with the model information. This example requires an inputMessage with the ModelTypeCode.
| |
Notice that the PCB reference name, DealershipDB, qualifies the Model segment name in the query string.
| | | | | | | | | | |
Segment-Qualifying Fields SQL dictates that whenever a field is common between two tables in an SQL query, the desired field must be table qualified to resolve the ambiguity. Similarly, whenever a field name is common in any two segments along a hierarchical path, the field must be segment qualified. For example, if a PCB has two segments, segment ROOT and segment CHILD, and both possess a field named id, any query referencing the id field must be segment qualified. The following example is incorrect because the id field is not segment qualified: SELECT id FROM PCBName.CHILD WHERE id=’10’
| | | |
The following example is correct because the id field is segment qualified:
| | | | | | | |
Recommendations: v For performance reasons, always segment qualify fields (unless readability is seriously sacrificed). A performance improvement is realized since IMS Java does not need to search through all the segments to locate the field and check for ambiguity. v It is not necessary to provide the PCB reference name on the query unless the query is ambiguous without it; however, it is recommended that you always provide it to remove ambiguity and to remove the need for checking.
SELECT CHILD.id FROM PCBName.CHILD WHERE ROOT.id=’10’
|
Chapter 3. Accessing an IMS Database
35
SQL Grammar public boolean getModelDetails(InputMessage inputMessage, ModelOutput modelOutput) throws IMSException {
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
// Parse the input message for ModelTypeCode String queryString = "SELECT * from DealershipDB.Model where ModelTypeCode = " + "’" + inputMessage.getString("ModelTypeCode").trim() + "’"; // Create a statement and execute it to get a ResultSet try { Statement statement = connection.createStatement(); ResultSet results = statement.executeQuery(queryString); // Send back the result of the query // Note: since "ModelTypeCode" is unique - only 1 row // is returned if (results.next()) { modelOutput.setString("ModelTypeCode", results.getString("Type").trim()); modelOutput.setString("Make", results.getString("CarMake").trim()); modelOutput.setString("Model", results.getString("CarModel").trim()); modelOutput.setString("Year", results.getString("CarYear")); modelOutput.setString("CityMiles", results.getString("EPACityMileage").trim()); modelOutput.setString("HighwayMiles",results.getString ("EPAHighwayMileage").trim()); modelOutput.setString("Price", results.getString("Price").trim()); modelOutput.setString("Horsepower", results.getString("Horsepower").trim()); return true; } else { reply("Unknown Type"); return false; } } catch (SQLException e) { reply("Query Failed:"+ e.toString()); return false; }
}
| | | | | |
Figure 12. Example of SELECT Query Results
Note: Note the use of trim() in Figure 12. The method trim() is used because IMS character fields are padded with blanks if they are not long enough. It trims off the extra blanks in the return.
| | | | |
Figure 12 illustrates the use of a Statement object for executing an SQL query. You can also use a PreparedStatement object to execute an SQL query. A PreparedStatement object has two advantages over a Statement object: v The SQL can be parsed one time for many executions of the query v You can build the query and use substitute values with each execution
| | | | | | |
The following two queries are equivalent: SELECT CarModel FROM DealerDB.Model WHERE CarYear=’1989’ SELECT Model.CarModel FROM DealerDB.Model WHERE Model.CarYear=’1989’
36
IMS Java User’s Guide
SQL Grammar In IMS Java, you specify only the segment furthest down the hierarchy in the FROM clause. You can query different segments by preceding the field name with the segment name, as in:
| | | | | | | |
SELECT Dealer.DealerName,CarModel FROM DealershipDB.Model WHERE CarMake=’Ford’
FROM A FROM clause in IMS Java differs from standard SQL in that no explicit joins are required nor allowed. Rather, the deepest segment to be accessed should be listed in the FROM clause. This then implies a join of all the segments starting with the one listed in the FROM clause up the hierarchy to the root. For more information see “JDBC Access Method” on page 24.
| | | | | |
WHERE
| | | | |
By using IMS Java to write IMS applications, you can avoid the long process of coding segment search arguments (SSAs) for every segment in the path leading to the segment being queried. Instead, you can use the IMS Java API for SQL queries to retrieve results from any segment in the path leading to the segment being queried.
| | |
The primary difference between SQL queries to relational databases and JDBC queries to IMS using IMS Java is that the hierarchical structure of an IMS database eliminates the need for the join required for tables in relational databases.
| | | | | | |
For example, Figure 13 is a query to a relational database for the address of a dealership that sells a particular car model that you are looking for (AnyCarModel): SELECT Dealer.Address FROM Dealer.Model WHERE Model.CarMake = ’AnyCarModel’ AND Dealer.DealerName = Model.CarrierName
| |
Figure 13. Sample Query
| |
You must query two independent tables (Dealer and Model) and indicate how they are joined in the WHERE clause.
| | | | | |
In an IMS Java application, you can write the query in Figure 14 to access the same data in a hierarchical database in a WHERE clause: SELECT Dealer.Address FROM DealershipDB.Model WHERE Model.CarMake = ’AnyCarModel’
| |
Figure 14. Sample Query
| | | | |
In a hierarchical database, all data in segments along the hierarchical path to the target segment are implicitly included in the query results and therefore do not need to be explicitly stated. In Figure 14, the information about the Dealer segment is included in the result set, because it is along the hierarchical path to the Model segment.
Chapter 3. Accessing an IMS Database
37
SQL Grammar | | | | |
However, in the case of the asterisk operator (*) in a SELECT query, a path call is not made. In the sample query below, only the fields from the Model segment are retrieved.
| |
If fields from more than one segment are desired, they must all be explicitly requested in the SELECT clause.
| | | | | | | |
You can use the following operators between field names and values in individual predicates: < <= = =< < !=
| |
You can combine multiple predicates with AND and OR operators. However, you cannot use parentheses and AND always takes precedence over OR.
|
SELECT * FROM DealershipDB.Model
INSERT
| | | | | |
An INSERT statement inserts a segment instance with the specified data under any number of parent segments matching the criteria specified in the WHERE clause. All column names must be in the statement, except when the value of a field is specifically set in the database view. For more information see “Adding Default Values for Fields of a Segment” on page 99. Figure 15 shows an example of an INSERT statement that inserts a field in the database:
| | | | | | | | |
String insertString = "INSERT INTO DealershipDB.Sales " + "(DateSold, PurchaserLastName, PurchaserFirstName, " + "PurchaserAddress, SoldBy, StockVINumber)" + " VALUES (’07032000’, ’Beier’, ’Otto’, " + "’101 W. 1st Street, Springfield, OH’, " + "’S123’, ’1ABCD23E4F5678901234’) " + "WHERE Dealer.DealerNumber = ’A123’" + "’ AND ModelTypeCode = ’K1’)";
| | | | |
Figure 15. Sample INSERT Statement
It is possible to set default values for any field in a segment. For more information see “Adding Default Values for Fields of a Segment” on page 99. A difference between JDBC queries to relational databases and IMS is that standard SQL does not have a WHERE clause in an INSERT statement, as tuples are just being inserted into the table specified after the INTO keyword. In an IMS DL/I database, you are actually inserting a new instance of the specified segment, so you need to know where in the database this segment occurrence needs to be placed. In the case of an INSERT statement, the WHERE clause is necessary in all cases except when inserting a root segment. In the case of a prepared statement, the list of values can have a ? as the value that can be substituted before the statement is executed. For example:
| | | | | | | | |
38
IMS Java User’s Guide
SQL Grammar INSERT INTO DealerDB.Model(ModelTypeCode, CarMake, CarModel, CarYear, Price, EPACityMileage, EPAHighwayMileage, Horsepower) VALUES (?,?,?,?,?,?,?,?) WHERE Dealer.DealerNumber=?
| | | | | |
DELETE
| | | | |
A DELETE statement can delete any number of segment occurrences matching the criteria specified in the WHERE clause. A DELETE statement with a WHERE clause also deletes the child segments of the matching segments. If no WHERE clause is specified, all of the segment occurrences of that type are deleted as are all of its child segment occurrences. Figure 16 shows an example of a DELETE statement:
| | | | | | | | | | | | |
String updateString = "DELETE from DealershipDB.Order WHERE " + "Dealer.DealerNumber = ’" + dealerDesired+ "’ AND " + "OrderNumber = ’" + orderDesired + "’"; try { Statement statement = connection.createStatement(); int results = statement.executeUpdate(updateString); ... } catch (SQLException e) { ... }
| | | |
Figure 16. Sample DELETE Statement
UPDATE
|
An UPDATE statement modifies the value of any number of segment occurrences.
| | | |
An UPDATE statement applies its SET operation to each instance of a specified segment with matching criteria in the WHERE clause. If the UPDATE statement does not have a WHERE clause, the SET operation is applied to all instances of the specified segment.
| | | | | | | | | | | | | | |
A SET clause contains at least one assignment. In each assignment, the values to the right of the equal sign are computed and assigned to columns to the left of the equal sign. For example, the UPDATE statement in Figure 17 is called to accept an order. When a customer accepts an order, the car’s “SerialNo” and delivery dates are filled in:
| | |
String updateString = "UPDATE DealershipDB.Order " + "SET SerialNo = ’" + inputMessage.getString("StockVINumber").trim() + "’, " + "DeliverDate = ’" + inputMessage.getString("Date").trim() + "’ WHERE OrderNumber = ’" + inputMessage.getString("OrderNumber").trim() + "’";
Figure 17. Sample UPDATE Statement
Chapter 3. Accessing an IMS Database
39
SQL Grammar |
JDBC Prepared Statements for SQL
| | | |
To improve performance of your IMS Java application, use JDBC prepared statements for the SQL. The PreparedStatement completes the initial steps in preparing queries only once so that you only need to provide the parameters before each repeated database call.
| | | |
The PreparedStatement performs the following only once before repeated database calls are made: 1. Parses the SQL 2. Cross-references the SQL with the IMS Java DLIDatabaseView 3. Builds SQL into SSAs before a database call is made
| |
Recommendations for JDBC
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Although the JDBC interface to an IMS database follows the relational paradigm closely, remember that the segments are physically stored in a hierarchical database, which affects the semantics of your JDBC calls to some extent. To avoid unexpected results, or potential performance problems, consider the following: v When performing a SELECT, generally try to supply predicates in the WHERE clause for all levels down the hierarchy to your target segment. – If you supply a predicate in the WHERE clause for some target segment somewhere down the hierarchy, and omit predicates for its parents, then IMS will scan all candidate segments at the parent levels in an attempt to match the predicate you have supplied. For example, if you are retrieving a second level segment and you supply a a predicate for that second level segment, but do not supply one for the root segment, then IMS may perform a full database scan, testing every second-level segment under every root against the predicate. This has performance implications, particularly at the root level, and may result in unexpected segments being retrieved.
| | |
Note: When considering the effects of the database hierarchy on your JDBC operations, you can find a description of the hierarchy, as it appears in your application view, in the DLIModel Java Report.
– A similar consideration applies to locating segments for UPDATEs. v When inserting a new segment, generally try to supply predicates in the WHERE clause for all levels down the hierarchy to your target new segment. If you omit a predicate for any level down to the insert target segment, then IMS will choose the first occurrence of a segment at that level that allows it to satisfy remaining predicates, and perform the insert in that path. This may not be what you intended. To take an example of a three-level database, if you insert a third-level segment, supply a predicate for the root, but none at the second-level, your new segment will always be inserted under the first second-level segment under the specified root. v When deleting a segment that is not a bottom-level segment in its hierarchy (in other words, a leaf segment), be aware that you have, in effect, cascaded deletes down the remaining segments in that hierarchical subtree. The entire family of segments of all types that are located hierarchically below your target deleted segment will also (generally) be deleted. v Although not solely related to hierarchies, note that when providing predicates to identify a segment, the search is generally faster if the predicate is qualified on a primary or secondary index key field, rather than simply a ″search field″. Primary and secondary key fields are identified for each segment in the DLIModel Java Report.
40
IMS Java User’s Guide
IMS Java Hierarchic Database Interface | |
IMS Java Hierarchic Database Interface
| | | | |
Even though you can use the lower-level package to access IMS data, it is recommended that you use the JDBC package. This package is included for experienced IMS application developers who need more access than the higher-level package provides. The IMS Java Hierarchic Database Interface contains the following objects and classes:
| | | |
DLIConnection A DLIConnection object represents a connection with a set of DL/I databases or views (as many PCBs as are in the PSB). It provides the interface to read, update, insert, and delete segments in a DL/I database.
| | | |
DLISegment DLISegment is the class that represents segments in a DL/I database. It registers the types of data stored in a segment by providing an array of DLITypeInfo objects. Definition: Setter and getter functions use the type information to automatically locate and convert data in the byte array to the requested format. These setter and getter functions can locate data based on both its offset in the DLITypeInfo array (fastest) or by using the name of the field included in the type information.
| | | | | | | | |
DLITypeInfo DLITypeInfo, contained in the base package, defines the type, offset, and length of a field in the byte array of a DLISegment. DLITypeInfo supports all DB2 for OS/390 data types, including packed decimal.
| |
SSA
| | | | | |
SSAList SSAList represents a collection of SSA objects and converts the list to the byte array necessary to invoke the JavaToDLI methods. The combination of SSAList, SSA, and SSAQualification statement allows an application to specify a Segment Search Argument list that fully supports all of its features.
| | | |
SSAQualificationStatement An SSAQualificationStatement represents logical qualification statements to a Segment Search Argument. Qualification statements support both key search fields and search fields.
| | | | |
DLIRecord DLIRecord represents the set of segment occurrences from a root segment down the hierarchy to the leaf segment. The DLIConnection methods getUniqueRecord and getNextRecord update a DLIRecord object using a path call (“D” command code).
| | |
DLISegmentInfo DLISegmentInfo is a “wrapper” class that links a DLISegment object to its parent in the DL/I database hierarchy.
| | | | |
DLIDatabaseView DLIDatabaseView represents an application’s view of the segments in a DL/I database. It is built as an array of DLISegmentInfo objects, which bind a DLISegment object to its parent DLISegment object. DLIDatabaseView therefore defines the segment hierarchy. DLIDatabaseView also provides
SSA represents a Segment Search Argument. It provides methods to add command codes and qualification statements.
Chapter 3. Accessing an IMS Database
41
IMS Java Hierarchic Database Interface named lookup of the DLISegment objects. This feature is used by the DL/I JDBC implementation to locate a DLISegment object from the name of a segment used in a query.
| | | |
Application Programming Using DLIConnection
| | | | | | | | | |
To use DLIConnection to read, update, insert, and delete segment instances, your application should: 1. Acquire DLISegment object for each segment using the cloneSegment method on the subclassed DLIDatabaseView 2. Provide a subclass of DLIDatabaseView that defines the segment hierarchy accessed by the application
| | | |
You may create the required classes by coding them manually (see Appendix A, “Manually Creating IMS Java Metadata Classes” on page 99), or by running the DLIModel utility (See Chapter 5, “DLIModel Utility” on page 61). It is recommended that you use the DLIModel utility wherever possible.
|
3. Create a DLIConnection object to access the database 4. Create an SSAList object 5. Invoke the database access methods of DLIConnection to read, write, or delete segments from the database
Creating a DLIConnection Object
| |
A DLIConnection object must be created in one of two ways: v By providing a DLIDatabaseView object v By providing the fully qualified name of the DLIDatabaseView
| | |
When coding directly to DLIConnection, it is faster to create and pass the DLIDatabaseView object, because it simplifies finding the class by its name. Figure 18 illustrates how to create a DLIConnection object:
| | |
DealerDatabaseView dealerView = new DealerDatabaseView(); DLIConnection connection = DLIConnection.createInstance(dealerView);
|
| | | |
Figure 18. Creating a DLIConnection Object
Building SSAs
| | | | | |
SSAs are used to identify the segment to which a DL/I call applies. Due to the hierarchical structure DL/I uses, you often have to specify several levels of SSAs to access a segment at a low level in the hierarchy. An SSAList is a collection of one or more SSAs and the SSAList is what is used in making any DL/I call. The SSAList is also where you specify which database you want to access within a DLIDatabaseView by providing the PCB reference name.
| |
Figure 19 on page 43 illustrates how to create an SSAList that will find all “Alpha” cars made in 1989:
|
42
IMS Java User’s Guide
IMS Java Hierarchic Database Interface | | | | | | | | | | | | | | | | | | | | | | |
// Create an SSAList SSAList modelSSAList = SSAList.createInstance("DealershipDB"); // Construct an unqualified SSA for the Dealer segment SSA dealerSSA = SSA.createInstance("Dealer"); // Construct a qualified SSA for the Model segment SSA modelSSA = SSA.createInstance("Model", "CarMake", SSA.EQUALS, "Alpha"); // Add an additional qualification statement modelSSA.addQualification(SSA.AND, "CarYear", SSA.EQUALS, "1989"); // Add the SSAs to the SSAList modelSSAList.addSSA(dealerSSA); modelSSAList.addSSA(modelSSA);
Figure 19. Creating an SSAList
Accessing DL/I Data using SSAs You can now issue a database call by invoking the desired access method on DLIConnection passing in: v the SSAList v an instance of the segment, that will be the intended target of the database call results
| | |
This passed-in instance should be obtained by calling the cloneSegment method on the DLIDatabaseView. Finally, the passed-in segment can be examined for the results of the query.
| | | | | | | |
The following example demonstrates calling and printing-out the results using the SSAList built in the preceding section: DLISegment model = dealerView.cloneSegment("Model"); boolean recordRead = connection.getUniqueSegment(model, modelSSAList); while (recordRead) { System.out.println("Car Name: " + model.getString("ModelName")); recordRead = connection.getNextSegment(model, modelSSAList); }
|
Chapter 3. Accessing an IMS Database
43
IMS Java Hierarchic Database Interface
44
IMS Java User’s Guide
| |
Chapter 4. Writing a Java Application Program
| | |
This chapter uses the sample applications shipped with IMS Java to show how to write IMS Java applications in different environments. For information on expanding and locating these files, see the Readme file in the samples directory.
| | | | |
All samples use a car dealership example and use JDBC for database processing. All samples process a common set of databases, and the jobs to define and load these databases are contained in the directory samples/dealership/databases. For information on how to run the database definition and load jobs, see the IMS sample Readme file in the directory samples/dealership/ims/Readme. In this Chapter: v “IMS Applications” v “CICS Applications” on page 59 v “DB2 Stored Procedures” on page 59
IMS Applications Overview of IMS Application Processing Using the IMS Java classes, you can write applications for the following types of IMS dependent regions: | | | | | | | |
Java message processing (JMP) regions JMP regions are similar to MPP regions, but JMP regions only allow the scheduling of Java message-processing programs. A JMP is started when there is a message in the queue for the JMP and IMS schedules the message to be processed. JMP programs are executed through transaction codes submitted by users at terminals and from other application programs. Each transaction code represents a transaction that the JMP processes. A single program can also be started from multiple transaction codes.
| | | | | | | |
JMP programs are very flexible in how they process transactions and where they send the output. JMP programs send any output messages back to the message queues and processes the next message with the same transaction code. The program continues to run until there are no more messages with the same transaction code. JMPs share the following characteristics: v They are small v They can produce output that is needed immediately
| | | | | | |
Java batch processing (JBP) regions JBP regions run flexible programs that perform batch-type processing online and can access the IMS message queues for output (similar to non-message–driven BMPs). JBPs are started by submitting a batch job with, for example, JCL or a TSO session. JBPs are like BMPs, except that they cannot read input messages from the IMS message queue (for example: there is no IN= parameter in the startup procedure).
| |
IMS Java applications can run in a DB/DC and DBCTL environments. IMS Java does not support batch processing.
© Copyright IBM Corp. 2000, 2002
45
IMS Applications
Running Java Applications After determining the appropriate type of Java program to use, you must give your program specific instructions from the terminal to run it. You can access programs from terminals by providing one of the following types of input: IMS Commands Start with slash (/). For example: /START.
| |
Related Reading: See IMS Version 7 Command Reference for more information on IMS commands. Transaction message A transaction message is routed to an application program for processing. The program destination is defined by the 1- to 8-byte transaction code included as the first part of the input message. Message switch A message switch is routed to another terminal. The terminal destination is defined by the 1- to 8-byte terminal name included as the first part of the input.
Message Queuing After you provide input in one of the forms described above, the message is either queued or sent directly to command process or modules. Specifically, all full-function database input and output messages are placed in message queues, waiting to be enqueued to their destinations or points of completion. However, before getting to the points of completion, IMS message queues are held in buffers in main storage until they are either directed to their destination or there is a backlog of messages arriving in the queue. If there are more messages entering the queue than exiting, IMS writes messages to the message queue data sets until they are directed to their final destinations. Related Reading: See the IMS Primer for general information on IMS message queues.
Reading and Writing Messages to the Message Queue in Java A basic IMS Java application involves the input and receipt of multiple messages from the message queue, much like applications in other languages. IMS Java applications are invoked by transactions; that is, a user at a terminal can communicate with the application program and IMS. The actual applications are built with the application package classes using the IMS Java classes and methods.
Building an IMS Java Application by Example | | | | | |
In “Introduction to the Example Environment” on page 23, a sample application program is introduced. The sample program uses an automobile dealership program for illustration purposes. This and other automobile dealership applications are available in the samples.tar file shipped with the IMS Java product (See the Readme file in the samples directory for instructions on how to expand and access these sample applications).
| | |
Related Reading: For a full specification of the classes used in this chapter, see the JavaDoc shipped with IMS Java. If using the default installation directory, the JavaDoc is in directory usr/lpp/ims/imsjava71/docs/.
Using IMS Java to Build a Message Processing Application To build an IMS Java message processing application, follow these steps: 1. Subclass IMSApplication.
|
46
IMS Java User’s Guide
IMS Applications
|
The entry point into the business application is via the doBegin method of the subclass, which is described in “Subclass IMSApplication and Implement main() and doBegin()” on page 48. The doBegin method is an abstract method in the base class, IMSApplication. Important: The main method of your subclass must call the begin method of the base class, IMSApplication. The begin method of the base class then performs initialization and calls the abstract doBegin method that was implemented in your subclass. 2. Receive and send IMSFieldMessages.
| | |
3. Perform a commit before processing the next message by calling IMSTransaction.getTransaction().commit() by calling IMSTransaction.getTransaction().abend().
| | | |
Subclass IMSFieldMessage to Define Any Input Messages: Figure 20 gives an example of subclassing IMSFieldMessage to define an input message that accepts a two-byte type code of a car model to query a car dealership database for available car models.
| | | | | | | | |
This example code subclasses IMSFieldMessage to make the fields in the message available to the program and creates an array of DLITypeInfo objects for the fields in the message. For the DLITypeInfo, the code identifies first the field name, then the data type, the position, and finally the length of the individual fields within the array. This allows the application to use the access functions within IMSFieldMessage to automatically convert the data from its format in the message to a Java type that the application can process. In addition to the message-specific fields it defines, IMSFieldMessage provides access functions that allow it to determine the transaction code and the length of the message.
| | | | | | | | | | | | | | | | |
package dealership.application; import com.ibm.ims.db.*; import com.ibm.ims.base.*; import com.ibm.ims.application.*; /* Subclasses IMSFieldMessage to define application’s input messages */ public class InputMessage extends IMSFieldMessage { /* Creates array of DLITypeInfo objects for the fields in message */ final static DLITypeInfo[]fieldInfo={ new DLITypeInfo("ModelTypeCode", DLITypeInfo.CHAR, 1, 2) };
}
public InputMessage() { super(fieldInfo, 2, false); }
Figure 20. Subclass IMSFieldMessage: Input Message Sample Code
| | |
Subclass IMSFieldMessage to Define any Output Messages: Figure 21 on page 48 gives an example of subclassing IMSFieldMessage to define an output message that displays the available car models from a type code query.
| | | | |
This example code creates an array of DLITypeInfo objects and then passes that array, the byte array length, and the boolean value false (indicates a non-SPA message) to the IMSFieldMessage constructor. For each DLITypeInfo object, you must first identify the field data type, then the field name, the field offset in the byte array, and finally the length of the byte array. Chapter 4. Writing a Java Application Program
47
IMS Applications package dealership.application; import com.ibm.ims.db.*; import com.ibm.ims.base.*; import com.ibm.ims.application.*;
| | | | | | | | | | | | | | | | | | | | | | | |
/*Subclasses IMSFieldMessage to define application’s output messages */ public class ModelOutput extends IMSFieldMessage { /* Creates array of DLITypeInfo objects for the fields in message */ final static DLITypeInfo[] fieldInfo={ new DLITypeInfo("Type", DLITypeInfo.CHAR, 1, 2), new DLITypeInfo("Make", DLITypeInfo.CHAR, 3, 10), new DLITypeInfo("Model", DLITypeInfo.CHAR, 13, 10), new DLITypeInfo("Year", DLITypeInfo.DOUBLE, 23, 4), new DLITypeInfo("CityMiles", DLITypeInfo.CHAR, 27, 4), new DLITypeInfo("HighwayMiles", DLITypeInfo.CHAR, 31, 4), new DLITypeInfo("Horsepower", DLITypeInfo.CHAR, 35, 4) }; public ModelOutput() { super(fieldInfo, 38,false); } }
|
Figure 21. Subclass IMSFieldMessage: Output Message Sample Code
| | | | |
Subclass IMSApplication and Implement main() and doBegin(): The example code shown in Figure 22 on page 49 demonstrates how to perform the following actions: 1. Subclassing IMSApplication. 2. Instantiating the subclass in the main method.
| | | | | | | | |
3. Calling the IMSApplication.begin() method. 4. Implementing the application in the doBegin() method of the subclass. (See “Programming Models for IMS Java Applications” on page 49 for more information on the normal flow of this method) 5. Querying the database for a specific model that matches the input model type code. This method is not implemented yet and is explained more fully in Chapter 3, “Accessing an IMS Database” on page 23. 6. Returning detailed information as output about that specific model if it is available at the dealership. 7. Returning an error message if the model is not available at the dealership.
|
48
IMS Java User’s Guide
IMS Applications | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
package dealership.ims; import com.ibm.ims.application.*; public class IMSAuto extends IMSApplication {1 IMSMessageQueue messageQueue = null; InputMessage inputMessage = null; ModelOutput modelOutput = null; public IMSAuto() { super(); } public static void main(String args[]) { IMSAuto imsauto = new IMSAuto(); 2 imsauto.begin(); 3 } public void doBegin() throws IMSException { 4 messageQueue = new IMSMessageQueue(); inputMessage = new InputMessage(); modelOutput = new ModelOutput(); while(messageQueue.getUniqueMessage(inputMessage)) { if (!inputMessage.getString ("ModelTypeCode").trim().equals("")){ if (getModelDetails(inputMessage, modelOutput))5 messageQueue.insertMessage(modelOutput); 6 } else { reply("Invalid Input"); 7 } IMSTransaction.getTransaction().commit(); }
}
public void reply(String errmsg) throws IMSException{ ErrorMessage errorMessage = new ErrorMessage(); errorMessage.setString("MessageText",errmsg); messageQueue.insertMessage(errorMessage);
} }
Figure 22. Subclass IMSApplication Sample Code
| | | | | | | | | | |
Note: IMSMessageQueue.getUniqueMessage returns true if a message was read from the queue and false if one was not. Also, IMSTransaction.getTransaction().commit must be called before receiving subsequent messages from the queue.
Programming Models for IMS Java Applications The following programming models outline the supported structure for IMS applications that run in JMP regions or JBP regions. The models are not complete, but show the normal flow of the doBegin method (See 4 in the previous section) for both the JDBC and SSA access methods. These models use JDBC, but for the SSA database access method, database access happens in the same places in the program flow as with JDBC.
Chapter 4. Writing a Java Application Program
49
IMS Applications | | |
JMP Programming Models
| | |
JMP programs are started when IMS receives a message with a transaction code for the JMP program and schedules the message. JMP programs end when there are no more messages with that transaction code to process.
| | | | | | | | | | | | | | | | | | | | | | | | |
JMP Program Without Rollback: Every time the program runs, the program connects to an IMS database and disconnects when it has processed all of the messages. A transaction begins when the program gets an input message and ends when the program commits the transaction. Database processing is done only after the getUniqueMessage call and before the commit call. The program cannot perform database processing after the commit call and either before the next getUniqueMessage call or the return.
| | | | | | | | | | | | | | | | | | | | | | | | | | | |
JMP Program using Rollback: A JMP program can roll back database processing and output messages any number of times during a transaction. A rollback call backs out all database processing and output messages to the most recent commit. The transaction must still end with a commit call when the program issues a rollback call, even if there is no further database processing or messages after the rollback.
JMP programs get input messages from the IMS message queue, access IMS databases, commit transactions, and can send output messages.
public void doBegin() ... {
//Application logic runs
conn = DriverManager.getConnection(...); //Establish DB connection repeat { MessageQueue.getUniqueMessage(...);
}
}
//Get input message, which
results=statement.executeQuery(...); //Perform DB processing ... MessageQueue.insertMessage(...); //Send output messages ... IMSTransaction.commit(); //Commit and end transaction
conn.close(); return;
public void doBegin() ... {
//Close DB connection
//Application logic runs
conn = DriverManager.getConnection(...); //Establish DB connection repeat { MessageQueue.getUniqueMessage(...);
//Get input message, which
results=statement.executeQuery(...); //Perform DB processing ... MessageQueue.insertMessage(...); //Send output messages ... IMSTransaction.rollback(); //Back out of DB processing and //output messages results=statement.executeQuery(...); //Perform more DB processing //(optional) ... MessageQueue.insertMessage(...); //Send more output messages //(optional) ... IMSTransaction.commit(); //Commit and end transaction
50
IMS Java User’s Guide
IMS Applications | | | | |
}
}
conn.close(); return;
//Close DB connection
| | | | | | | | | | | | | | | | | | | | | | | | | | | | |
JMP Program With Per-Transaction Connections: A JMP program needs to open a database connection only once to process multiple transactions. However, a JMP program can open and close a database connection for each transaction processed. The disadvantage is that you add some code complexity and lose a small amount of performance. But an advantage is it might be easier to port the application to other environments where per-transaction connections are required. These per-transaction connections are required if the program uses DB2 interoperability to issue any DB2 database calls.
| | | |
JBP Programming Models
| | | | | | | | | | | | | | | | | | |
JBP Program Without Rollback: A JBP program connects to a database, performs database processing, sends any output messages, periodically commits, and disconnects from the database at the end of the program. The program must issue a final commit before ending.
public void doBegin() ... {
//Application logic runs
conn = DriverManager.getConnection(...);
//Establish DB connection
repeat { conn = DriverManager.getConnection(...); //Establish DB connection
} }
MessageQueue.getUniqueMessage(...);
//Get input message, which
results=statement.executeQuery(...); ... MessageQueue.insertMessage(...); ... conn.close();
//Perform DB processing
IMSTransaction.commit();
//Commit & end transaction
//Send output messages //Close DB connection
return;
JBP application programs are similar to JMP programs, except that JBP programs do not receive input messages from the message queue. The program should periodically issue commit calls, except for PROCOPT=GO programs.
public void doBegin() ... {
//Application logic runs
conn = DriverManager.getConnection(...);
//Establish DB connection
repeat { repeat { results=statement.executeQuery(...); //Perform DB processing ... MessageQueue.insertMessage(...); //Send output messages ... } }
IMSTransaction.commit();
//Periodic commits divide work
Chapter 4. Writing a Java Application Program
51
IMS Applications | | | |
}
conn.close(); return;
//Close DB connection
JBP Program using Rollback: Like JMP programs, JBP programs can also back out of database processing and output messages. A final commit call is required before the program can end, even if no database processing occurs or output messages are sent after the last rollback call.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
public void doBegin() ... { conn = DriverManager.getConnection(...);
//Application logic runs //Establish DB connection
repeat { repeat { results=statement.executeQuery(...); //Perform DB processing ... MessageQueue.insertMessage(...); //Send output messages ... IMSTransaction.rollback(); //Back out of DB //messages
} }
}
results=statement.executeQuery(...); //Perform more DB //processing (optional) ... MessageQueue.insertMessage(...); //Send more output //messages (optional) ...
IMSTransaction.commit();
conn.close(); return;
//Periodic commits divide work //Close DB connection
Additional Programming Considerations This section describes additional programming conderations: v “Conversational Transactions” v “Handling Multi-Segment Messages” on page 54 v “Coding and Accessing Messages with Repeating Structures” on page 55 v “Flexible Reading of Multiple Input Messages” on page 56
| | | | |
Conversational Transactions A conversational program runs in a JMP region and processes conversational transactions that are made up of several steps. It does not process the entire transaction at the same time. A conversational program divides processing into a connected series of terminal-to-program-to-terminal interactions. Use conversational processing when one transaction contains several parts.
| | | | |
A non-conversational program receives a message from a terminal, processes the request, and sends a message back to the terminal. A conversational program receives a message from a terminal and replies to the terminal, but it saves the data from the transaction in a scratch pad area (SPA). Then, when the person at the terminal enters more data, the program has the data it saved from the last message in the SPA, so it can continue processing the request without the person
52
IMS Java User’s Guide
IMS Applications | |
at the terminal having to enter the data again. The application package classes enable applications to be built using IMS Java.
| | |
Related Reading: For more information on conversational and nonconversational transaction processing, see IMS Version 7 Administration Guide: Transaction Manager.
| | | | | | | | |
Defining a SPA Message: Here are the steps to define a SPA message in a conversational program:
| | | | | | | |
1. Define the SPA message (including the boolean as a SPA parameter). By default, all messages going to (input) and from (output) an IMS Java application are transmitted as EBCDIC character data. To use a different type of encoding, you must call the IMSFieldMessage inherited member setDefaultEncoding and provide the new encoding. This encoding can be any Java supported encoding. In Figure 23, the default encoding is specified as UTF-8. public class SPAMessage extends IMSFieldMessage { static DLITypeInfo[] fieldInfo = { new DLITypeInfo("SessionNumber",DLITypeInfo.SMALLINT,1, 2), new DLITypeInfo("ProcessCode", DLITypeInfo.CHAR, 3, 8), new DLITypeInfo("LastName", DLITypeInfo.CHAR, 11,10), new DLITypeInfo("FirstName", DLITypeInfo.CHAR, 21,10), new DLITypeInfo("Extension", DLITypeInfo.CHAR, 31,10), new DLITypeInfo("ZipCode", DLITypeInfo.CHAR, 41, 7), new DLITypeInfo("Reserved", DLITypeInfo.CHAR, 48,19) }; public SPAMessage() { super(fieldInfo, 66, true); setDefaultEncoding("UTF-8"); } } Figure 23. Defining a SPA Message
2. Read the SPA message before reading the application messages: | | | | | | | | | | | | | | | | | | | | | |
try { // Get the SPA data msgReceived = msgQ.getUniqueMessage(spaMessage); } catch (IMSException e) { if (e.getStatusCode() != JavaToDLI.MESSAGE_QUEUED_PRIOR_TO_LAST_START) throw e; } if (!msgReceived) outputMessage.setString("Message","UNABLE TO READ SPA"); else if (!msgQ.getNextMessage(inputMessage)) // No input message received outputMessage.setString("Message","NO INPUT MESSAGE"); else if ((spaMessage.getShort("SessionNumber")==0) && (!inputMessage.getString("ProcessCode").trim().equals("END")) && (inputMessage.getString("LastName").trim().equals(""))) // New Conversation. User has to specify last name. outputMessage.setString("Message","LAST NAME WAS NOT SPECIFIED"); else { }
| | |
Figure 24. Reading the SPA Message
Chapter 4. Writing a Java Application Program
53
IMS Applications 3. Write the SPA message before sending any output messages: // Set spa data fields spaMessage.setString("ProcessCode", inputMessage.getString("ProcessCode")); spaMessage.setString("LastName", inputMessage.getString("LastName")); spaMessage.setString("FirstName", inputMessage.getString("FirstName")); spaMessage.setString("Extension", inputMessage.getString("Extension")); spaMessage.setString("ZipCode", inputMessage.getString("ZipCode")); spaMessage.incrementSessionNumber(); msgQ.insertMessage(spaMessage); Figure 25. Writing the SPA Message
4. End the conversation using the version of insertMessage containing a boolean isLast argument set to true: msgQ.insertMessage(spaMessage, true);
Conversational Transaction Sequence of Events: When the message is a conversational transaction, the following sequence of events occurs: 1. IMS removes the transaction code and places it at the beginning of a message segment. The message segment is equal in length to the SPA that was defined for this transaction during system definition. This is the first segment of the input message that is made available to the program. The second through the nth segments from the terminal, minus the transaction code, become the remainder of the message that is presented to the application program. 2. When the conversational program has prepared its reply, it inserts the SPA to IMS. The program then inserts the actual text of the reply as segments of an output message. 3. IMS saves the SPA and routes the message to the input LTERM (logical terminal). 4. If the SPA insert specified that another program is to continue the same conversation, the total reply (including the SPA) is retained on the message queue as input to the next program. This program then receives the message in a similar form. 5. A conversational program must be scheduled for each input exchange. The other processing continues while the operator at the input terminal examines the reply and prepares new input messages. 6. To terminate a conversation, the program places blanks in the transaction code field of the SPA and inserts the SPA to IMS. In IMS Java this happens when you call IMSMessageQueue.insertMessage with the boolean parameter isLast set to true. 7. The conversation can also be terminated if the transaction code in the SPA is replaced by any non conversational program’s transaction code, and the SPA is inserted to IMS. After the next terminal input, IMS routes that message to the other program’s queue in the normal way.
Handling Multi-Segment Messages
| | | |
It is possible in message driven applications to have multi-segment input messages. That is, more than one message needs to be read from the message queue in order to retrieve the entire message. When this occurs, you must provide a
54
IMS Java User’s Guide
IMS Applications | |
mapping for each message that is to be read from the queue and use the appropriate methods available from the IMSMessageQueue class.
| | | | | | | | | | | | | | | | | | | | | | | | |
The following code defines two input messages that comprise a multi-segment message:
| | | | | | | | | | | | | | | | | | |
The following code illustrates how the message queue is used to retrieve both messages:
|
Coding and Accessing Messages with Repeating Structures
public class InputMessage1 extends IMSFieldMessage { final static DLITypeInfo[] segmentInfo = { new DLITypeInfo("Field1", DLITypeInfo.CHAR, 1, 10), new DLITypeInfo("Field2", DLITypeInfo.INTEGER, 11, 4) };
}
public InputMessage1() { super(segmentInfo, 14, false); }
public class InputMessage2 extends IMSFieldMessage { final static DLITypeInfo[] segmentInfo = { new DLITypeInfo("Field1", DLITypeInfo.CHAR, 1, 10), new DLITypeInfo("Field2", DLITypeInfo.CHAR, 11, 8) };
}
public InputMessage2() { super(segmentInfo, 18, false); }
//Create a message queue IMSMessageQueue messageQueue = new IMSMessageQueue(); //Create the first input message InputMessage1 input1 = new InputMessage1(); //Create the second input message InputMessage2 input2 = new InputMessage2(); try { //Read the first message from the queue messageQueue.getUniqueMessage(input1); ... //Read the second message from the queue messageQueue.getNextMessage(input2); ... } catch (IMSException e) { ... }
Messages with repeating structures can be defined using a subclass of DLITypeInfo called DLITypeInfoList. DLITypeInfoList allows you to define an array of repeating structures in one object instead of multiple, individual DLITypeInfo objects. DLITypeInfoList is an object that stores an array of DLITypeInfo objects along with a count of its occurrences, thus allowing an input message to contain nested repeating structures. Figure 26 on page 56 is an example of an output message containing a set of“ Make,”“ Model,” and “Color” fields, with a count field to identify how many occurrences were stored:
Chapter 4. Writing a Java Application Program
55
IMS Applications | | | | | | | | | | | | |
public class ModelOutput extends IMSFieldMessage { static DLITypeInfo[] modelTypeInfo = { new DLITypeInfo("Make", DLITypeInfo.CHAR, 1, 20), new DLITypeInfo("Model", DLITypeInfo.CHAR, 21, 20), new DLITypeInfo("Color", DLITypeInfo.CHAR, 41, 20), }; static DLITypeInfo[] modelTypeInfoList = { new DLITypeInfo("ModelCount", DLITypeInfo.INTEGER, 1, 4), new DLITypeInfoList("Models", modelTypeInfo 5, 60, 100), }; public ModelOutput() { super(modelOutputTypeInfo, 6004, false); } }
| |
Figure 26. Example Output Message
Note: The creation of the DLITypeInfoList object has no provision for specifying its type. DLITypeInfoList hard codes the type of the fields to DLITypeInfo.TYPELIST. This design is not constrained to any specific level of nesting. Within the declaration of model TypeInfo in Figure 26, any of the array members could be instances of DLITypeInfoList. To access the nested structures defined in a DLITypeInfoList, use a dotted notation for specifying the fields and the index of the field within a repeating structure. This dotted notation can use either the field names or field indexes. For example, the “Color” field in the fourth“ Models” definition in ModelOutput would be accessed as “Models.4.Color” within the Model Output message. The following code sets the fourth “Color” in the ModelOutput message to “Red.” ModelOutput output= new ModelOutput(); output.setString("Models.4.Color", "Red");
The following code uses field indexes instead of field names to make the same change to the ModelOutput message: ModelOutput output= new ModelOutput(); output.setString("2.4.3", "Red");
Because DLISegment objects are defined using DLITypeInfo objects exactly like IMSFieldMessages, you can also use these repeating structures within your definitions of DLISegment subclasses. If you do this, however, and you wish to use DLIModel, you will have to modify the generated classes from the utility. DLIModel will not use DLITypeInfoList definitions in its generated classes. However, you cannot access fields defined in this manner using an SQL query.
| | | | | |
Flexible Reading of Multiple Input Messages There are times when an application needs to process multiple input messages that require different input data types. For example, the car dealership sample application supports requests to list models, show model details, find cars, cancel orders, and record sales. Each of these requests requires different input data. The following steps show you how to define the messages to support these requests and how to access the messages from the application. The letters in the code samples (for example, A) are described on page 58. 1. Define the primary input message. This is the message you pass to IMSMessageQueue.getUniqueMessage to retrieve all of your input messages. Your primary input message must have an I/O area large enough to contain any of the input requests that your application might receive. It should also contain at least one field in common with all your input messages that allows you to determine the input request. In this example, the common field is
56
IMS Java User’s Guide
IMS Applications “CommandCode,” and the maximum length of each message is 64 (the number passed to the IMSFieldMessage constructor): public class InputMessage extends IMSFieldMessage { final static DLITypeInfo[] fieldInfo = { new DLITypeInfo("CommandCode", DLITypeInfo.CHAR, 1, 20), A }; public InputMessage(DLITypeInfo[] fieldInfo) {
}
super(fieldInfo, 64, false); B }
Figure 27. Defining the Primary Input Message
2. Define separate input messages for each request. Each of these input messages contains the same “CommandCode” field as its first field. Each of these input messages also uses an IMSFieldMessage constructor that takes an IMSFieldMessage and a DLITypeInfo array. This constructor allows you to remap the contents of the primary input message using the same type of information with each request; therefore, you do not copy the I/O area of the message, only a reference to this area. Figure 28 on page 58 illustrates code that created the input messages for the requests “ShowModelDetails,” “FindACar,” and “CancelOrder.”
Chapter 4. Writing a Java Application Program
57
IMS Applications public class ShowModelDetailsInput extends IMSFieldMessage { final static DLITypeInfo[] fieldInfo = { new DLITypeInfo("CommandCode", DLITypeInfo.CHAR, 1, 20), C new DLITypeInfo("ModelTypeCode", DLITypeInfo.CHAR, 21, 2), }; public ShowModelDetailsInput(InputMessage inputMessage) { D super(inputMessage, fieldInfo); } } public class FindACarInput extends IMSFieldMessage { final static DLITypeInfo[] fieldInfo = { new DLITypeInfo("CommandCode", DLITypeInfo.CHAR, 1, 20), E new DLITypeInfo("Make", DLITypeInfo.CHAR, 21, 10), new DLITypeInfo("Model", DLITypeInfo.CHAR, 31, 10), new DLITypeInfo("Year", DLITypeInfo.CHAR, 41, 4), new DLITypeInfo("LowPrice", DLITypeInfo.PACKEDDECIMAL, 45, 5), new DLITypeInfo("HighPrice", DLITypeInfo.PACKEDDECIMAL, 50, 5), new DLITypeInfo("Color", DLITypeInfo.CHAR, 55, 10), }; public FindACarInput(InputMessage inputMessage) { F super(inputMessage, fieldInfo); } } public class CancelOrderInput extends IMSFieldMessage { final static DLITypeInfo[] fieldInfo = { new DLITypeInfo("CommandCode", DLITypeInfo.CHAR, 1, 20), G new DLITypeInfo("OrderNumber", DLITypeInfo.CHAR, 21, 6), new DLITypeInfo("DealerNumber", DLITypeInfo.CHAR, 21, 6), }; public CancelOrderInput(InputMessage inputMessage) H { super(inputMessage, fieldInfo); }
Figure 28. Creating the Input Messages
Note the following about Figure 28: v The CommandCode field is defined within every class at lines A, C, E, and G. This field must be defined in every message that reads the command code. If you do not define the field, you must adjust the offsets of the following fields to account for the CommandCode’s existence in the byte array. For example, you can delete the DLITypeInfo entry for “CommandCode” in CancelOrderInput, but the “OrderNumber” field must still start at offset 21. v The length of the base class, InputMessage, must be large enough to contain any of its subclasses. In this example, InputMessage is 65 bytes because the fields of FindACarInput require it B. v Each InputMessage subclass must provide a constructor to create itself from an InputMessage, as in lines D, F, and H. This constructor uses a new constructor in IMSFieldMessage, called a copy constructor.
58
IMS Java User’s Guide
IMS Applications Given this design, an application can provide message reading logic similar to Figure 29. while (getUniqueMessage(inputMessage)) { string commandCode=inputMsg.getString("CommandCode").trim(); if (commandCode.equals("ShowModelDetails")) { showModelDetails(new ShowModelDetailsInput(inputMessage)); } else if(commandCode.equals("FindACar")) { findACar(new FindACarInput(inputMessage)); } else { //process an error } }
Figure 29. Message Reading Logic
CICS Applications The following programming model outlines the supported structure for CICS applications that use IMS Java. The models are not complete, but show the normal flow of the application for both the JDBC and SSA access methods. This model use JDBC, but for the IMS Java hierarchic database interface method, database access happens in the same places in the program flow as with JDBC. public static void main(CommAreaHolder cah) { conn = DriverManager.getConnection(...);
//Receives control //Establish DB connection
repeat { results = statement.executeQuery(...); //Perform DB processing ... //send output to terminal }
}
conn.close(); return;
//Close DB connection
DB2 Stored Procedures The following programming model outlines the supported structure for DB2 Stored Procedures that use IMS Java. The models are not complete, but show the normal flow of the application for both the JDBC and SSA access methods. This model use JDBC, but for the IMS Java hierarchic database interface, database access happens in the same places in the program flow as with JDBC. public static void targetMethod(...) {
//Receives control with //input or output parameters
conn = DriverManager.getConnection(...);
//Establish DB connection
repeat { results = statement.executeQuery(...); //Perform DB processing ... } partmOut[...]=...;
//Move results to output //parameters Chapter 4. Writing a Java Application Program
59
IMS Applications
}
60
IMS Java User’s Guide
conn.close(); return;
//Close DB connection
| |
Chapter 5. DLIModel Utility
| |
This chapter contains information on the DLIModel utility including introductory and practical usage information.
| | | | | | |
In This Chapter: v “DLIModel Utility Overview” v “Requirements and Restrictions of the DLIModel Utility” on page 63 v “Output Types of the DLIModel Utility” on page 64
| |
v “Control Statements for the DLIModel Utility” on page 66 v “Running the DLIModel Utility” on page 74 v “Examples of Using the DLIModel Utility” on page 77
DLIModel Utility Overview
| | | |
Processing IMS databases with an IMS Java application requires that you describe the database view of your application’s PSB to IMS Java. You must do this by providing the name of a metadata class when establishing the JDBC database connection.
|
There are two ways you can prepare the metadata class for an application: v Provide the application PSB source and any related DBD source to the DLIModel utility, and specify the generation of the IMS Java metadata class.
| | | | | |
This is the recommended technique and is described in this chapter. v Code the metadata class manually. This is described further in Appendix A, “Manually Creating IMS Java Metadata Classes” on page 99.
| | | | | | | | | | |
You can use the DLIModel utility to: v Create IMS Java metadata classes to describe a PSB’s view of IMS databases, from PSB and DBD source. v Incorporate additional field information from XMI input files that describe COBOL copybook members. v Incorporate additional PCB, segment, and field information, or overrides of existing information, into the generated class from user-prepared input control statements. v Create a DLIModel Java Report (designed to assist Java application programmers), which describes the IMS Java view of the PSB and its databases.
| | | | | | |
The DLIModel utility can process most types of PSBs and databases. For example, IMS Java supports: v All database organizations except MSDB, HSAM, SHSAM, and GSAM
v Create an XMI description of the PSB and its databases.
v All types and implementations of logical relationships v Secondary indexes except for shared secondary indexes v Secondary indexes processed as stand-alone databases v PSBs that specify field-level sensitivity
|
© Copyright IBM Corp. 2000, 2002
61
DLIModel Utility Overview |
| | | | | | | |
Figure 30. The DLIModel Utility Inputs and Outputs
Figure 30 shows the inputs and outputs of the DLIModel utility. The actions of the utility are directed by control statements that you supply. PSB and DBD source members are read from their PDS or PDSE data sets and parsed by the utility to build an in-memory object model of the database structure and the PSB’s view of that structure. Multiple PSBs may be processed in a single run of the utility. The control statements can specify: v Which PSBs to process in this run v Aliases for PSBs, PCBs, segments, and fields
| | | | | | | |
v Data types and format masks for fields v XMI files that contain XMI descriptions of COBOL copybook members corresponding to segments v Additional field definitions for fields that were not defined in the DBD or COBOL copybook XMI file v Information that overrides PSB, DBD, and COBOL copybook XMI information
| |
v Default values for newly inserted segments When these inputs have all been processed and incorporated into the model, the utility generates various outputs that were requested through control statements.
| |
62
IMS Java User’s Guide
DLIModel Utility Overview | | |
You can request to have an IMS Java metadata class be generated for each PSB processed, together with a corresponding easy-to-read DLIModel Java Report for the Java programmer to use.
| | |
You can request an XMI description of the entire in-memory model (one description covers all PSBs and DBDs processed in the run). For details of this XMI output, see “XMI Description of the Databases” on page 65.
| |
You can also request a detailed trace file of the utility execution if one is necessary for problem resolution.
| |
Requirements and Restrictions of the DLIModel Utility
|
Requirements The following are the requirements to run the DLIModel utility. v PCBs in the PSB must be named, either through statement labels or the PCBNAME parameter. v If your application uses JDBC and the field list in a call includes fields from more than one segment in a hierarchic path, then IMS Java employs path calls. In this case you must include the PROCOPT=P option in the PCB or SENSEG statements, as appropriate. v If your application uses SSA database access, path calls are under your control, and you must choose PSB processing options depending on your processing, in the usual way.
| | | | | | | | | | | | | | | | | | | |
v This utility will not validate the PSB and DBD source. IBM strongly recommends that you generate DBDs, PSBs, and ACBs, correct all errors, and then run the DLIModel utility. v This utility follows all inter-DBD references when building its model, and may require access to DBDs that are not directly referenced by PCBs in the PSB. For example, when processing a PSB that references a main database with a number of secondary indexes, DLIModel needs access to the secondary index DBDs even if the PSB does not explicitly name any of these indexes for a secondary processing sequence, or for segment search purposes. Similarly, all DBDs related by logical relationships must be accessible. v You must maintain the length field in variable length segments on INSERT or UPDATE. v XMI input files must conform to the COBOL metamodel, which is part of the CAM metamodel of the OMG-accepted version of the UML specification for the Enterprise Application Integration (EAI) standard.
| | | | | | | | | | | | | |
Restrictions The DLIModel utility has the following restrictions. It cannot process: v MSDB, HSAM, SHSAM, and GSAM databases v Shared secondary indexes v PROCOPT=K option in a PSB SENSEG v The DLIModel utility does not use DLITypeInfoList classes in its generated classes. If you want to define repeating groups of fields in segments (other than by explicitly defining each group of fields separately) you will have to create the classes manually or modify the classes generated by DLIModel.
Chapter 5. DLIModel Utility
63
DLIModel Utility Overview | | |
v COBOL copybook XMI files, which supply additional information about field layouts, must describe the physical segments. The files cannot describe the logical database segment layouts.
| | |
Related Reading: For more information about IMS hierarchical databases, see the:IMS Version 7 Administration Guide: Database Manager and the IMS Version 7 Utilities Reference: System.
| |
Output Types of the DLIModel Utility This section discusses the different output types of the DLIModel utility.
| |
IMS Java Metadata Classes
| | |
The DLIModel utility produces the necessary metadata classes needed to develop IMS Java applications. However, the Java developer needs only to reference the DLIModel Java Report for information about the classes.
| |
Related Reading: For a description of the class source produced, refer to the Appendix A, “Manually Creating IMS Java Metadata Classes” on page 99.
|
DLIModel Java Report
| | | |
The DLIModel Java Report summarizes the structure of the IMS databases in a way that allows you to create IMS Java applications and to code SQL queries against the databases. With the DLIModel Report, you do not have to interpret the syntax of the IMS Java classes or refer to the DBD or PSB source.
| |
Related Reading: Sample DLIModel Java Reports are shown in each of the four examples in “Examples of Using the DLIModel Utility” on page 77.
| | | | | | |
PSB Description
| | | | |
PCB Description
| | | | | |
Segment Description
| | | |
Field Description
Within the DLIModel Java Report, a separate section is produced for each PSB named in a PSB statement of the control data set. The name of the generated class for the PSB is given first, which is either the name defined by the JavaName parameter or, if no JavaName is specified, the 8-character IMS PSB name. The report also gives the IMS PSB name and the package for this class, if one was specified in the OPTIONS control statement. Within each PSB, sections are listed for each PCB. Each PCB is identified by its IMS Java name, which is either the user-chosen JavaName, if one was specified, or the 8-character IMS PCB name. This is the PCB name that should be used in SQL queries to the database. Within each PCB, all segments are listed in hierarchical sequence. Segment descriptions are indented to illustrate the hierarchical dependencies. Each segment is identified by its IMS Java name, which is either the JavaName, if one was specified in the control data set, or the 8-character IMS Segment name. Use the IMS Java name for the segment in SQL queries to the database. Within each segment, fields are listed in the order in which they appear in the database DBD with any additional fields appended. Fields are of the following types:
64
IMS Java User’s Guide
DLIModel Utility Outputs | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Field that is physically resident in a DBD A field that is physically resident in a DBD is identified by its IMS Java name, which is either the user-chosen JavaName, if one was specified, or the 8-character IMS Field name. This is the name that should be used in SQL queries. A DBD field is further annotated as either a ++ Primary Key Field ++ if it is the sequence field of its segment, or a (Search field) if it is a non-sequence field. SQL queries with WHERE clauses qualified on Primary Key Fields will generally produce much faster response times than calls qualified on search fields, but both are allowed. These fields have their IMS Java type listed, and if necessary, their type qualifier string. They also have their Start position and Bytes listed. It is important to note that the Start and Bytes values describe the field’s properties in the original database segment, not necessarily its Start or Bytes as viewed from Java application. The primary purpose of the Start and Bytes values is to describe how these fields overlap or redefine each other in the database. They are otherwise unnecessary for writing SQL queries in the Java application. DBD secondary index search field A DBD secondary index search field (a field defined in the DBD with an XDFLD macro) is also identified through its IMS Java name, either user-chosen, or the DBD name. The field is annotated as ++ Secondary Key Field ++, and like a ++Primary Key Field ++ will produce fast responses to queries. However, secondary index search fields are not physically present in their segment and can not be retrieved from the Java ResultSet. In the report, secondary index search fields are followed by a list of their component search fields to assist you in creating a suitable string to use as a search argument in an SQL query. A secondary index field has no Start or Bytes value in the segment. It is essentially a virtual field and is used for search purposes only. Field that is not present in the DBD A field that is not present in the DBD is identified (for example, one that has been added by a Field control statement or by an XMI COBOL copybook description) by its Java name, if one is present, or by its 8-character name. Its start position, length, data type, and type qualifier are all listed. It has no key field or search field annotation in the report, indicating that it may not be used in an SQL WHERE clause. However, it may be retrieved from the result set following successful queries.
XMI Description of the Databases
| | | |
An XMI file, written in UTF-8 encoding, is produced by the utility if you specify genXMI=YES in the OPTIONS control statement. It describes all of the PSBs and their referenced DBDs processed in the entire run of the utility. DBDs shared by multiple PSBs or PCBs are only described once.
| | | | |
Samples of the XMI produced (converted from UTF-8 to EBCDIC encoding for viewing in an OS/390 environment) for each of the samples in this chapter are in the samples directories. To use a sample XMI file as input for an application, convert the file back to UTF-8 encoding. You can also run the utility using the sample input files to generate XMI files written in UTF-8 encoding.
| |
The XMI that is produced by the utility is based on a meta-model of IMS database defined in UML. This model is a package with a number of inheritance relationships
Chapter 5. DLIModel Utility
65
DLIModel Utility Outputs | |
to the OMG Common Warehouse Metamodel (CWM). However, only the IMS package itself is included and used in the DLIModel utility.
| | | | | | |
Directory /usr/lpp/ims/imsjava71/samples/dlimodel/model of the distribution media contains: v An EBCDIC-encoded XMI definition of the meta-model to view in an OS/390 environment. v A Rational Rose model file of the meta-model. This model file is at the 4.5/6.0 Model level, corresponding to Rose 98 or 98i. To view this file, you need a licensed and installed copy of a suitable level of the Rational Rose product.
|
DLIModel Trace The DLI Model utility can generate a trace file, named dlimodeltrace, if you need to resolve a problem with the utility. For the utility to generate the trace file, specify GenTrace=YES in the OPTIONS statement. You can also specify the path where the file is written by using the TracePath parameter.
| | | | | |
Control Statements for the DLIModel Utility
| | | | |
You must write control statements to specify certain options such as input and output data set names, and what PSBs and PCBs to use. You can also use the control statements to supply information to the utility about PSBs, PCBs, segments, and fields that cannot be extracted from the PSBs, DBDs, or COBOL copybook XMI files.
| | |
The control statements are supplied to the utility in a PDS member named in the EXEC statement PARM field of the MVS JCL, or in an HFS file named in a command line parameter in the MVS USS environment.
|
Control Data Set Rules
| |
You must include at least the following statements in your control statement data set:
| |
v OPTIONS Statement v PSB Statement for each PSB to be processed
|
Optionally, you can include the following statements in the control data set:
| |
v PCB Statement v SEGM Statement
| | |
v FIELD Statement v XDFLD Statement v INCLUDE Statement
| |
The following syntax diagram shows how to organize the control statements in the control data set.
|
66
IMS Java User’s Guide
OPTIONS Statement
\
PSB Statement
\ PCB Statement
Q
DLIModel Utility Control Statements | |
Q \ SEGM Statement
| |
\
Q
\ FIELD Statement
XDFLD Statement
Q \
QT INCLUDE Statement
| | | |
If you requested IMS Java metadata class source in the OPTIONS statement, each PSB that you specified results in a separate metadata .java file, and a corresponding DLIModel Java Report.
| | | | | |
A typical reason to include PCB, SEGM, and FIELD statements is to assign to these entities a customized name (referred to as an alias) that can be used in your Java program. You can choose a name that is more meaningful than the 8-character name given to these entities in the DBD and PSB source. You might also need to assign data types to fields, and to define additional fields that are important to your application but that were not defined in the segment in the DBD.
| | | | |
You do not need to include PCB, SEGM, or FIELD statements in your control statement set if all of the following statements are true of your application:
| |
Related Reading: For examples of control statement sets, refer to the examples in “Examples of Using the DLIModel Utility” on page 77.
| | |
The rules for ordering the control statements are as follows: v The OPTIONS statement must be first and only be present in a top-level control data set. v PCB statements must follow immediately after the PSB statement to which they belong. They may be in any order (for example, PCB statements need not be in the same order as they appear in the original PSB source).
| | | | | | | | | | |
v It can process PCBs, segments and fields by their 8-character IMS names. v It needs only fields that are defined in the DBD. v All fields can be processed as data type CHAR.
v FIELD statements must follow immediately after the SEGM for the physical segment to which they belong. However, Field statements may be in any order within their segment group. (for example, field statements need not be in the same sequence as they appear in the original DBD source)
| |
FIELD statements for existing fields and for new fields may be intermixed or grouped in any sequence. v INCLUDE statements can be positioned anywhere in a control data set, but not between: – PSB statement and any PCB statements that belong to it – SEGM statement and any FIELD statements that belong to it
| | |
You can nest multiple control data sets by using the INCLUDE statement. Nesting gives you the flexibility to store your control statements across multiple HFS files or PDS members for increased convenience and control.
| |
For example, a top-level file could contain the OPTIONS, PSB and PCB statements that specify a desired Java-class generation. Included files might each contain a Chapter 5. DLIModel Utility
67
DLIModel Utility Control Statements group of SEGM and FIELD statements that relate to an individual logical or physical DBD. You can reuse these latter files without change for other PSBs that reference the same databases and segments.
| | | |
Control Statement Rules
| | | | |
The control statement syntax is very flexible. Each statement consists of an identifier followed by keyword parameters. The identifier may start in any column. Each identifier, keyword, and variable must be separated by at least one whitespace character, unless it is already separated by an operator. Keyword parameters can occur in any order.
| | | |
If your control statements are held in an MVS data set, map the statements to multiple 80-character records, between columns 1 and 72 inclusive. Columns 73 through 80 are ignored, and may be used for sequence numbers if you wish. No continuation characters are required.
| | | |
If your control statements are held in an HFS file, any line length is acceptable, but you can optionally continue statements across multiple lines as in MVS. If you restrict your line length to less than 73 characters, your control statements can be moved between MVS data sets and HFS files without change.
| | |
Identifiers, parameter keywords, and predefined parameter values (such as, YES and NO) may appear in upper or lower case. Other parameter values (for example, user specified path or Java names) are case sensitive.
|
Control Statement Syntax
| | | |
OPTIONS Statement
|
The following diagram shows the syntax of the OPTIONS statement.
One OPTIONS control statement is required. The statement customizes the DLIModel utility by specifying where to find input, what output to produce, and where to put the output.
| |
QQ OPTIONS \ PSBds= IMS.qual.dsname(member)
| |
Q
Q \ DBDds= IMS.qual.dsname(member)
Q Package=
GenJavaSource=
| |
NO
GenXMI=
NO
packagename GenTrace=
NO Q
Q GenJavaSource=
YES
GenXMI=
YES
GenTrace=
Q
Q
| |
OutPath= path
|
68
IMS Java User’s Guide
YES
JavaSourcePath=
path
ReportPath=
path
DLIModel Utility Control Statements FieldOrder=
|
DEFAULT
Q
QT XMIPath= path
TracePath=
path FieldOrder=
OFFSET
| | | | | |
PSBds=IMS.qual.dsname(member) Required parameter specifies the data set name of the PSB source. If multiple parameters are specified, the utility opens and searches the data sets in the order of the PDSds parameters when it is reading a PSB. This action is similar to data set concatenation in an MVS JVL DD statement.
| | | | |
DBDds=IMS.qual.dsname(member) Required parameter specifies the data set name of the DBD source. If multiple parameters are specified, the utility opens and searches the data sets in the order of the DBDds parameters when it is reading a DBD. This action is similar to data set concatenation in an MVS JVL DD statement.
| | |
Package=packagename Optional parameter specifies the package that the generated IMS Java classes are for. A Java package statement is added to each .java file produced.
| | |
GenJavaSource=YES | NO Optional parameter specifies whether to generate IMS Java class source files and a DLIModel Java report.
| | | |
GenXMI=YES | NO Optional parameter specifies whether to generate an XMI file (dlimodelxmi.xmi) that describes the database model based on all PSBs and corresponding databases processed by the utility.
| | |
GenTrace=YES | NO Optional parameter specifies whether to generate a trace file (named dlimodeltrace) of the utility run.
| | | |
OutPath=path Optional parameter specifies the HFS directory where the utility writes the output files, unless you specify path names for specific output files. The default is the current directory.
| | |
JavaSourcePath=path Optional parameter specifies the HFS directory where the utility writes the IMS Java class files. Overrides OutPath.
| | |
ReportPath=path Optional parameter specifies the HFS directory where the utility writes the DLIModel Java report. Overrides OutPath.
| | |
XMIPath=path Optional parameter specifies the HFS directory where the utility writes the generated XMI. Overrides OutPath.
| | |
TracePath=path Optional parameter specifies the HFS directory where the utility writes the trace file. Overrides OutPath.
| | |
FieldOrder=DEFAULT | OFFSET Optional parameter specifies the order of the fields of segments in the generated IMS Java class.
Chapter 5. DLIModel Utility
69
DLIModel Utility Control Statements | | |
DEFAULT Fields are in the same order as in the DBD and followed by any new fields defined by the control statements.
| |
OFFSET Fields are in the order their start positions.
| | |
PSB Statement
|
The following diagram shows the syntax of the PSB statement.
|
QQ PSB
The PSB statement is required because it defines which PSBs that the utility uses. Multiple PSB statements are allowed, unless the * wildcard form is specified.
PSBName=
name nameprefix* *
QT JavaName=
name
| PSBName=name | nameprefix | * Required parameter specifies the PSB to be used by the utility.
| | | |
name Process the PSB with the name name.
| | |
nameprefix* Process all PSBs with the nameprefix in the specified PSB data set input file.
|
*
Process all PSBs in the specified data set input file.
| | |
JavaName=name Optional parameter specifies the name of the generated IMS Java class only if using one PSB. Ignored if using nameprefix or ALL for PSBName.
| | |
PCB Statement
|
The following diagram shows the syntax of the PCB statement.
| |
QQ PCB
| | |
PCBName=name Required parameter specifies the eight-character PCB name that you want to assign an alias to.
| | |
JavaName=name Required parameter specifies the Java alias for the PCB, which will be used in the Java application. Must be unique for each PSB.
| | |
SEGM Statement
| |
For physical segments, the SEGM statement: v Identifies a physical segment in a DBD v Optionally supplies a Java alias for the segment v Specifies an XMI COBOL copybook file containing additional information about the segment
The PCB statement is optional. It specifies a Java alias for a PCB. All PCB statements for a PSB must follow the PSB statement.
PCBName= name
JavaName=
name
The SEGM control statement is optional and used for physical and logical segments.
| | |
70
IMS Java User’s Guide
QT
DLIModel Utility Control Statements |
v Groups the FIELD statements that follow the SEGM statement
|
For logical segments, the SEGM statement:
| | |
v Identifies a logical segment in a logical DBD v Specifies a Java alias for the segment v Cannot be followed by any FIELD statements
| | | | |
If the utility cannot find the segment, it issues a warning (instead of an error) and ignores any following FIELD statements. Because the utility only issues an error, you can create control statement files that provide information about many segments and their fields, not all of which are used by the particular PSB being processed.
| |
If an XMI COBOL copybook file was named for a segment, the fields that it defines are merged by name with the fields defined in the DBD.
|
The following diagram shows the syntax of the SEGM statement.
|
QQ SEGM DBDName= name SegmentName= name JavaName= name
QT
XMIName= name
| | | |
DBDName=name Required parameter specifies the eight-character DBD name where the segment is defined.
| |
SegmentName=name Required parameter specifies the segment name in the DBD.
| | | |
JavaName=name Required parameter specifies the Java alias for the segment, which will be used in the Java application. Must be unique for each DBD. If specified, overrides any value that might have been set from a COBOL XMI file.
| | | |
XMIName=name Optional parameter specifies the name of an XMI COBOL copybook file that may provide additional information about the segment and its existing fields, and definitions of new fields. XMI input is only allowed for physical segments.
| | | | |
FIELD Statement
| | | | |
When adding information for an existing DBD field, you must specify the 8-character DBD name of the field using the Name parameter. You can optionally specify the starting position (Start parameter) and length (Bytes parameter) of the field. If you do, DLIModel checks these values against the DBD and produces an error message if they do not match.
| | | | |
To add information to a non-DBD field that has been inputted from COBOL copybook XMI file, specify a Java name (JavaName parameter) that matches the name of the copybook field. Do not specify a DBD 8-character field name (Name parameter). Not specifying a Name parameter, for example, to add a default value to a COBOL copybook field.
The FIELD statement is optional. It specifies information about a field or defines a new field for a segment in a physical DBD. All FIELD statements for a segment must immediately follow the SEGM statement. However, FIELD statements can be in any order and mixed with XDFLD statements.
Chapter 5. DLIModel Utility
71
DLIModel Utility Control Statements | | | | |
To define a new field in the segment, do not specify a DBD 8-character field name. Instead, specify a unique Java name (JavaName parameter) that does not match any Java field name in the segment. You must also specify a starting position (Start parameter) and a length (Bytes parameter) for the new field. You can include other attributes (for example, data type or default value) for the new field.
| | |
To define a new field, you must specify the starting position (Start parameter), the length (Byte parameter) of the field, and the name (Name or JavaName parameter) of the field.
|
The following diagram shows the syntax of the FIELD statement.
| |
QQ FIELD
| |
Q
| | |
Q
| | | |
Name=name Specifies eight-character field name as defined in the DBD. Must be unique within segment. Identifies this control statement as applying to an existing field within the DBD. Do not specify this parameter if you are specifying a new field.
| | |
Start=int Specifies the starting position of the field in the segment. The first byte in the segment is 1. Required for new fields and optional for existing fields.
| | |
Bytes=name Specifies the length of the field in the segment. Required for new fields and optional for existing fields.
| | | | | | |
JavaName=name Specifies the Java alias for the field. Java names of Field statements and XDFLD statements must be unique within a segment. Required if defining a new field and optional for existing fields. If a field has been inputted from COBOL copybook XMI file with the same name as the JavaName parameter on a control statement, the control statement is applied to this COBOL copybook field.
| | | | | | | | | | | | | | | |
JavaType=string Optional parameter specifies the Java type of the field. Default is CHAR. Allowed types: CHAR FLOAT DOUBLE SMALLINT INTEGER BIGINT ZONEDDECIMAL TIME CARCHAR TINYINT BIT TYPELIST BINARY
Q Name= name
Start=
int
Bytes=
name Q
JavaName= name
JavaType=
string
TypeQualifier=
string QT
Default= string
72
IMS Java User’s Guide
DLIModel Utility Control Statements | | |
PACKEDDECIMAL DATE TIMESTAMP
|
Overrides any value that was set by the XMI COBOL copybook file.
| | | | | | | |
TypeQualifier=string Required parameter for some Java types. Specifies type qualifier for the following Java types: PACKEDDECIMAL ZONEDDECIMAL DATE TIME TIMESTAMP
| |
Related Reading: For more information on determining the syntax of type qualifiers, see “Supported Data Types in IMS Java” on page 32.
| | | | |
Default=string Optional parameter specifies the default value for the field. The default value is used for new instances of the segment when an application does not define a value for the field. The string must be formatted to match the data type qualifier properties of the field.
| | | |
XDFLD Statement
| | | | | |
You must identify a secondary index field (which must be an existing field that was defined in the DBD) by the eight-character name because secondary index fields do not have a starting position in the segment. Secondary index fields do not have a data type. Therefore, you must create a single string that contains the concatenated search fields, each correctly encoded for its data type, when using the index field in a JDBC Select. An index field cannot be fetched from the JDBC Resultset.
|
The following diagram shows the syntax of the XDFLD statement.
| |
QQ XDFLD
| | |
Name=name Required parameter specifies the eight-character name of the secondary index field as defined in the DBD.
| |
JavaName=name Required parameter specifies the Java alias for the field.
| | | | | |
INCLUDE Statement
| | | |
Important: Do not put an INCLUDE statement between PSB statements and PCB statements or between SEGM statements and FIELD statements. Putting the INCLUDE statement between these statements breaks the required relationship between them.
The XDFLD statement is optional. It specifies a Java alias for an existing secondary index field in a segment. The DXFLD statements must follow the SEGM statement that corresponds to the segment with the secondary indexes in the DBD.
Name= name
JavaName=
name
QT
The INCLUDE statement is optional and is only allowed in the top-level control statement data set. It specifies a PDS member or HFS file of additional control statements to be included in the top-level data set. The included data set must be the same type (PDS or HFS) as the top-level data set. You are allowed any number of INCLUDE statements in the top-level data set.
Chapter 5. DLIModel Utility
73
DLIModel Utility Control Statements |
The following diagram shows the syntax for the INCLUDE statement.
|
QQ INCLUDE
Dataset=
IMS.qual.dsname(member) path/filename
QT
| | | |
Dataset=IMS.qual.dsname(member) | path/filename Required parameter specifies the PDS member of HFS file containing the control statements that are to be included in the top-level data set.
| | | |
Comment Statement
| |
The Comment Statement is optional. It indicates that a line in the PDS member is a comment the same way as you would do in Java code. For example: // The two slashes indicate that this line is a comment.
Running the DLIModel Utility You can run the DLIModel utility either as a standard OS/390 MVS job, or from the command prompt under MVS Unix System Services (USS). For the latter alternative, see “Running the DLIModel Utility From MVS Unix Systems Services” on page 77.
| | | | |
Running the DLIModel Utility as an MVS Job
| | | | | | |
An MVS procedure is provided in order to run DLIModel as an MVS job. This procedure must initially be moved from its distribution library (where it is named, DFSMODEL) to the procedure library from which your installation executes IMS database utilities. It must be tailored to your installation’s requirements, and optionally renamed to a name of your choosing. See “DLIModel Utility Setup” on page 19. This book assumes that you have renamed the procedure to DLIMODEL (all upper case).
| | |
Since the DLIModel utility is a Java application, the DLIMODEL procedure runs it on OS/390 using BPXBATCH, an MVS-provided utility that runs any OS/390 UNIX shell command or executable.
|
The DLIMODEL procedure has two steps: v Step 1 executes the DLIModel utility (a Java application) by invoking the MVS utility BPXBATCH. The data set name of a PDS control data set is provided to the utility through the EXEC statement PARM field. This step contains DD statements for the utility’s standard output steams, STDOUT and STDERR, which are directed to temporary HFS files. Other utility inputs and outputs are read from, or sent to data sets and files with names specified by the control data set, and do not have DD statements. v Step 2 redirects STDOUT and STDERR to MVS SYSOUT streams where they can be viewed using your usual procedures, for example, using SDSF.
| | | | | | | | |
The following is the DLIMODEL procedure, which runs the DLIModel utility:
| |
74
IMS Java User’s Guide
Running the DLIModel Utility | | | | | | | | | | | | | | | | | | | | | | | | | | |
//DLIMODEL PROC DSNAME=,SOUT=’*’ //******************************************************************** //* THIS PROC RUNS THE IMS JAVA UTILITY IN BATCH MODE //******************************************************************** //STEP1 EXEC PGM=BPXBATCH, // PARM=’SH "/usr/lpp/ims/imsjava71/dlimodel/go" "&DSNAME"’ //STDENV DD DUMMY //STDOUT DD PATH=’/tmp/&SYSUID..out’, // PATHOPTS=(OWRONLY,OCREAT,OTRUNC), // PATHMODE=SIRWXU //STDERR DD PATH=’/tmp/&SYSUID..err’, // PATHOPTS=(OWRONLY,OCREAT,OTRUNC), // PATHMODE=SIRWXU //*---------------------------------------------//* Redirect stdout and stderr output to SYSOUT: //STEP2 EXEC PGM=IKJEFT01,DYNAMNBR=300,COND=EVEN //SYSTSPRT DD SYSOUT=&SOUT //HFSOUT DD PATH=’/tmp/&SYSUID..out’ //HFSERR DD PATH=’/tmp/&SYSUID..err’ //STDOUTL DD SYSOUT=&SOUT,DCB=(RECFM=VB,LRECL=133,BLKSIZE=137) //STDERRL DD SYSOUT=&SOUT,DCB=(RECFM=VB,LRECL=133,BLKSIZE=137) //SYSPRINT DD SYSOUT=&SOUT // PEND
Figure 31. Sample DLIModel Utility PROC
|
PROC Statement Parameters
| |
DSNAME The name of the control data set for the utility
|
SOUT Sets the class for all SYSOUT output in the procedure.
|
Step 1 EXEC Statement Parameters
| |
PGM=BPXBATCH Runs the MVS BPXBATCH utility.
|
PARM Runs the utility as a Java application under the UNIX shell.
| |
/usr/lpp/ims/imsjava71/dlimodel/go is the path and file name of an HFS script file.
| | | | | |
DSNAME is a string parameter containing the fully qualified data set name of the top-level control data set, which contains the DLIModel utility control statements (as described in section “Control Statements for the DLIModel Utility” on page 66). DSNAME must refer to an MVS partitioned data set member. The format is: qual1.qual2.dsname(member)
|
The named data set should be F or FB type with an LRECL=80.
|
Step 1 DD Statements
| | |
STDENV DD Contains statements that set the Java environment variables. You should not need to use this DD statement.
| | | |
STDOUT DD The destination to which the utility in STEP 1 directs standard output. This includes messages recording the normal execution of the utility. This output is redirected by STEP 2 to the standard MVS SYSOUT destination. Chapter 5. DLIModel Utility
75
Running the DLIModel Utility | | | | |
STDERR DD The destination to which the utility in STEP 1 directs standard error output. This includes error and warning messages related to the execution of the utility. This output is redirected by STEP 2 to the standard MVS SYSOUT destination.
| | |
SYSTSIN DD Provides control cards for the MVS utility IKJEFT01 to copy the temporary HFS output files to the MVS SYSOUT destination.
|
Step 2 EXEC Statement Parameters
| | |
PGM=IKJEFT01 Runs the MVS utility IKJEFT01, which redirects STDOUT and STDERR to MVS SYSOUT.
| | |
DYNAMNBR See OS/390: Unix Systems Services User’s Guide and OS/390: Unix Systems Services Command Reference.
| | |
COND See OS/390: Unix Systems Services User’s Guide and OS/390: Unix Systems Services Command Reference.
|
Step 2 DD Statements
| |
SYSTEPRT DD IKJEFT01 utility output.
| |
HFSOUT DD Input from the temporary STDOUT file from step 1.
| |
HFSERR DD Input from the temporary STDERR file from step 1.
| |
STDOUTL DD Output destination for the STDOUT stream.
| |
STDERRL DD Output destination for the STDERR stream.
| |
SYSPRINT DD IKEJEFT01 utility output.
| | | | | |
SYSTSIN DD Must be added to execution JCL. Provides control statement input for the IKJEFT01 utility that redirect HFSOUT and HFSERR streams to the STDOUL and HFSERRL destinations. For example:
| | | | | |
As provided, the utility expects that you specify an HFS script file, /usr/lpp/ims/imsjava71/dlimodel/go, in its PARM= field. For details on whether this script file is required in your installation, how to prepare it, and alternatives, see “DLIModel Utility Setup” on page 19. Note that if a script file is required, its preparation is a one-time task. Once prepared it will be effectively invisible to users submitting the utility to MVS from ISPF.
| | |
Related Reading: For more information about the MVS BPXBATCH utility, see OS/390: Unix Systems Services User’s Guide and OS/390: Unix Systems Services Command Reference.
OCOPY INDD(HFSOUT) OUTDD(STDOUTL) OCOPY INDD(HFSERR) OUTDD(STDERRL)
76
IMS Java User’s Guide
Running the DLIModel Utility | | | | | | | | |
The following JCL an example of a job that runs the DLIMODEL procedure:
| |
In this example, the IKJEFT01 SYSTSIN DD statement is provided with control cards to copy the temporary HFS outputs to MVS SYSOUT destinations.
|
//BPXAUTP6 JOB CLASS=Z,MSGCLASS=E,MSGLEVEL=(1,1), // TIME=(9),USER=OMVSADM,PASSWORD=xxxxxxx, // REGION=32M //TEST EXEC DLIMODEL,DSNAME=’DQEIVP.ECDEV37.JCL(CNTRSTMT)’ //STEP2.SYSTSIN DD * OCOPY INDD(HFSOUT) OUTDD(STDOUTL) OCOPY INDD(HFSERR) OUTDD(STDERRL) /*
Running the DLIModel Utility From MVS Unix Systems Services
| | | | |
In addition to the JCL PROC, you can run the DLIModel utility from a prompt under MVS Unix System Services (USS). You can use this method if you are more familiar with a Unix environment than with MVS JCL or ISPF. See “DLIModel Utility Setup” on page 19 for recommendations on adjusting your shop’s Java environment for running the DLIModel utility as a Java application.
|
The command syntax for running the utility as a Java application is as follows:
| |
QQ java
| |
java Runs JDK 1.3.1 java command
| |
com.ibm.ims.metagen.DLIModel Main class of the DLIModel utility
| |
path/ControlFile HFS file for control data set
| |
com.ibm.ims.metagen.DLIModel path/ControlFile
QT
Examples of Using the DLIModel Utility
| |
The section shows examples of how the DLIModel utility uses DBDs, PSBs, control statements, and JCL to create IMS Java classes and DLIModel Java reports.
| | | | |
The examples in this section are in the following directories:
| | | | |
/usr/lpp/ims/imsjava71/samples/dlimodel/example1/ /usr/lpp/ims/imsjava71/samples/dlimodel/example2/ /usr/lpp/ims/imsjava71/samples/dlimodel/example3/ /usr/lpp/ims/imsjava71/samples/dlimodel/example4/
Example 1. Simple Example Figure 32 on page 78 shows a DBD for a single physical database with two segments. It is referenced by the PSB, with a single PCB and two sensitive segments shown in Figure 33 on page 78.
Chapter 5. DLIModel Utility
77
DLIModel Utility Examples DBD
NAME=DEALDB1,ACCESS=(HDAM,OSAM), RMNAME=(DFSHDC40,1,5,200) DATASET DD1=DFSDLR SEGM NAME=DEALER,PARENT=0,BYTES=61 FIELD NAME=(DLRNO,SEQ,U),BYTES=4,START=1,TYPE=C FIELD NAME=DLRNAME,BYTES=30,START=5,TYPE=C SEGM NAME=MODEL,PARENT=DEALER,BYTES=37 FIELD NAME=(MAKE,SEQ,U),BYTES=10,START=1,TYPE=C FIELD NAME=MODEL,BYTES=10,START=11,TYPE=C DBDGEN FINISH END
| | | | | | | | | | | | | | | | | | | | |
X
Figure 32. Physical DBD for Simple Example
PCB1
| | | | |
PCB TYPE=DB,DBDNAME=DEALDB1,PROCOPT=A,KEYLEN=28 SENSEG NAME=DEALER,PARENT=0 SENSEG NAME=MODEL,PARENT=DEALER PSBGEN PSBNAME=AUTPSB1,LANG=ASSEM,CMPAT=YES END
Figure 33. PSB for Simple Example
Note that the PCB is given a name, as required by IMS Java. In this case a label is used, but a PCBNAME= parameter is also acceptable. A simple MVS JCL execution of the DLIModel utility, using this PSB and DBD, is shown in Figure 34.
| | | | | | | | | |
//BPXAUTP6 JOB CLASS=Z,MSGCLASS=E,MSGLEVEL=(1,1) //TEST EXEC DLIMODEL // DSNAME="DSNAME=IMSVS.TEST1.JCL(EXAMPLE1)" //STEP2.SYSTSIN DD * OCOPY INDD(HFSOUT) OUTDD(STDOUTL) OCOPY INDD(HFSERR) OUTDD(STDERRL) /*
| | | | | | | | | |
Figure 34. Minimal MVS JCL stream
The control data set, DSNAME=IMSVS.TEST1.JCL(EXAMPLE1) is shown in Figure 35. Options GenJavaSource=yes PSBds=IMSVS.TEST1.PSBSRC DBDds=IMSVS.TEST1.DBDSRC PSB PSBName=AUTPSB1
| | | | | | | | | |
Figure 35. Control Data Set for Simple Example
The utility processes a single PSB named AUTPSB1 and its DBD, DEALDB1. The utility reads the PSB and DBD from data sets IMSVS.TEST1.PSBSRC and IMSVS.TEST1.DBDSRC. It generates an IMS Java class only for this PSB, since no other output is requested. The name of the generated class is AUTPSB1DatabaseView (the first 7 characters of this name are set from the PSB name) and the class is written to the HFS file, AUTPSB1DatabaseView.java under the current directory. STDOUT is redirected to SYSOUT, but (in the absence of errors)
78
IMS Java User’s Guide
DLIModel Utility Examples | | |
consists of only startup and normal completion messages. The DLIModel Java Report (produced whenever IMS Java classes are generated) is written to the HFS file, AUTPSB1JavaReport.txt.
| | | | | | | | | | | | | | | | | |
The DLIModel Java Report, shown in Figure 36, describes the generated IMS Java metadata class AUTPSB1DatabaseView.
| | | | |
DLIModel Java Report ======================== Class: AUTPSB1DatabaseView
generated for PSB: AUTPSB1
================================================== PCB: PCB1 ================================================== Segment: DEALER Field: DLRNO Type=CHAR Start=1 Length=4 ++ Primary Key Field ++ Field: DLRNAME Type=CHAR Start=5 Length=30 (Search Field) ================================================== Segment: MODEL Field: MAKE Type=CHAR Start=1 Length=10 ++ Primary Key Field ++ Field: MODEL Type=CHAR Start=11 Length=10 (Search Field)
Figure 36. DLIModel Java Report for Simple Example
Notice these things in the DLIModel Java Report: v The class name, AUTPSB1DatabaseView, is based on the IMS PSB name.
| |
v The PCB name, PCB1, is the same as the label in the PSB PCB statement. v The segment names are the same as the names of the DBD SEGM statements.
|
v The field names are the same as the names in the DBD FIELD statements.
| | | |
These names are all derived from the 8-character (maximum) names in the IMS PSB and DBD source members. These are the defaults that are used when no control statements or XMI COBOL copybook files are supplied to specify more developer-friendly names.
| | |
Each field line displays the starting position and length of the field in the segment, and its type. Again, since there are no control statements or XMI COBOL copybook files to specify otherwise, the type of all fields defaults to CHAR.
| | | | | | |
Each field in the example is annotated as either a primary key field, or a search field. Primary key fields are fields that were designated as a SEQ field in the DBD. Search fields are non-SEQ fields from the DBD. Both field types may be used in the WHERE clause of a JDBC statement, but Primary Key Fields generally provide a much faster response. In the example, these are the only field types, since there are no control statements or XMI COBOL copybook files to add additional fields, and no secondary indexes.
| | | |
Example 2. Example With a Logical Relationship Figure 37 on page 80 and Figure 38 on page 80 show two physical DBDs linked by a bidirectional logical relationship.
Chapter 5. DLIModel Utility
79
DLIModel Utility Examples | | | | | | | | | | | | | | | | | | | |
DBD
NAME=EMPDB2,ACCESS=(HDAM,OSAM), RMNAME=(DFSHDC40,1,5,200) DATASET DD1=DFSEMPL SEGM NAME=EMPL,PARENT=0,BYTES=56 LCHILD NAME=(SALESPER,DEALDB2),PAIR=EMPSAL,POINTER=DBLE FIELD NAME=(EMPNO,SEQ,U),BYTES=6,START=1,TYPE=C FIELD NAME=LASTNME,BYTES=25,START=7,TYPE=C FIELD NAME=FIRSTNME,BYTES=25,START=32,TYPE=C SEGM NAME=EMPSAL,PARENT=EMPL,PTR=PAIRED, SOURCE=((SALESPER,DATA,DEALDB2)) FIELD NAME=(DLRNO2,SEQ,U),BYTES=4,START=1,TYPE=C (LPK) SEGM NAME=EMPLINFO,PARENT=EMPL,BYTES=61 FIELD NAME=(STATE,SEQ,M),BYTES=2,START=51,TYPE=C FIELD NAME=ADDRESS,BYTES=61,START=1,TYPE=C FIELD NAME=STREET,BYTES=25,START=1,TYPE=C FIELD NAME=CITY,BYTES=25,START=26,TYPE=C DBDGEN FINISH END
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
X
X
Figure 37. EMPDB2 Physical DBD for Logical Relationship Example
DBD
NAME=DEALDB2,ACCESS=(HDAM,OSAM), X RMNAME=(DFSHDC40,1,5,200) DATASET DD1=DFSDLR SEGM NAME=DEALER,PARENT=0,BYTES=61 FIELD NAME=(DLRNO,SEQ,U),BYTES=4,START=1,TYPE=C FIELD NAME=DLRNAME,BYTES=30,START=5,TYPE=C FIELD NAME=CITY,BYTES=10,START=35,TYPE=C SEGM NAME=MODEL,PARENT=DEALER,BYTES=37 FIELD NAME=(MODKEY,SEQ,U),BYTES=24,START=3, X TYPE=C FIELD NAME=MODTYPE,BYTES=2,START=1,TYPE=C FIELD NAME=MAKE,BYTES=10,START=3,TYPE=C FIELD NAME=MODEL,BYTES=10,START=13,TYPE=C FIELD NAME=YEAR,BYTES=4,START=23,TYPE=C FIELD NAME=MSRP,BYTES=5,START=27,TYPE=P SEGM NAME=ORDER,PARENT=MODEL,BYTES=74 FIELD NAME=(ORDNBR,SEQ,U),BYTES=6,START=1,TYPE=C FIELD NAME=LASTNME,BYTES=25,START=7,TYPE=C FIELD NAME=FIRSTNME,BYTES=25,START=32,TYPE=C FIELD NAME=DATE,BYTES=10,START=57,TYPE=C LCHILD NAME=(SINDXA,SINDEX2),POINTER=INDX XDFLD NAME=XFLD2,SRCH=(LASTNME,FIRSTNME,ORDNBR), X DDATA=DATE SEGM NAME=SALESPER,PARENT=((DEALER,),(EMPL,PHYSICAL,EMPDB2)),X BYTES=6, X POINTER=(LPARNT,LTWINBWD,TWINBWD), X RULES=(VVV) FIELD NAME=(EMPNO,SEQ,U),BYTES=6,START=1,TYPE=C (LPK) SEGM NAME=SALESINF,PARENT=SALESPER,BYTES=15 FIELD NAME=QUOTA,BYTES=5,START=1,TYPE=C FIELD NAME=SALESYTD,BYTES=5,START=6,TYPE=C FIELD NAME=COMSSION,BYTES=5,START=11,TYPE=C DBDGEN FINISH END
| | | | |
Figure 38. DEALDB2 Physical DBD for Logical Relationship Example
In these two physical DBDs, note that segment, EMPL in EMPDB2 is a logical parent, and it is pointed to by physical logical child, SALESPER in DEALDB2. The
80
IMS Java User’s Guide
DLIModel Utility Examples | | | |
relationship is bidirectional with virtual pairing, and the sequence of the logical child chain is defined through the key field, DLRNO2 in the virtual logical child, EMPSAL in EMPDB2 -- that is actually the destination parent concatenated key from DEALER in DEALDB2.
| | | | | | | | | | | | | | | | | | |
Figure 39 shows a logical DBD based on these two physical DBDs. The logical DBD is rooted in the EMPDB2 physical DBD, and crosses the logical relationship to the DEALDB2 DBD via EMPSAL and DEALER to include the SALESINF segment from the DEALDB2 database. The EMPSAL and DEALER segments form a concatenated segment, with data from both physical segments present in the I/O area.
| | | | | | | | | | | | | | | | | | | | | | | | | | | |
DBD NAME=EMPLDB2,ACCESS=LOGICAL DATASET LOGICAL SEGM NAME=EMPL,PARENT=0,SOURCE=((EMPL,,EMPDB2)) SEGM NAME=DEALER,PARENT=EMPL, SOURCE=((EMPSAL,DATA,EMPDB2),(DEALER,DATA,DEALDB2)) SEGM NAME=SALESINF,PARENT=DEALER, SOURCE=((SALESINF,,DEALDB2)) SEGM NAME=EMPLINFO,PARENT=EMPL, SOURCE=((EMPLINFO,,EMPDB2)) DBDGEN FINISH END
X X X
Figure 39. Logical DBD for Logical Relationship Example
Figure 40 shows a PSB, containing a single PCB that references this logical DBD. Note that field-level sensitivity is used in the logical segment, SALESINF. Only two of the three fields in that segment are visible. Also, in this example, the field lengths and start positions are specified so that there is an empty single byte between the two fields. PCB1
PCB TYPE=DB,DBDNAME=EMPLDB2,PROCOPT=A,KEYLEN=14 SENSEG NAME=EMPL,PARENT=0 SENSEG NAME=DEALER,PARENT=EMPL SENSEG NAME=SALESINF,PARENT=DEALER SENFLD NAME=QUOTA,START=1 SENFLD NAME=SALESYTD,START=7 SENSEG NAME=EMPLINFO,PARENT=EMPL PSBGEN PSBNAME=AUTPSB2,LANG=ASSEM,CMPAT=YES END
Figure 40. PSB with Field-Level Sensitivity for Logical Relationship Example
The JCL stream to execute the utility is similar to that presented in Figure 34 on page 78 of the previous Example 1. The minimal control data set presented in Example 1 could also work for this example. However, the control data set IMSVS.TEST1.JCL(EXAMPLE2) shown in Figure 41 on page 82 makes use of a few more control statements for purposes of illustration.
Chapter 5. DLIModel Utility
81
DLIModel Utility Examples Options PSBds=IMSVS.TEST1.PSBSRC DBDds=IMSVS.TEST1.DBDSRC GenJavaSource=yes Package=example2 GenXMI=yes GenTrace=yes PSB PSBName=AUTPSB2 JavaName=EmployeeView
| | | | | | | | | | | | | | | |
Figure 41. Control Data Set for Logical Relationship Example
The utility processes AUTPSB2, and the DBDs, DEALDB2 and EMPDB2. As already discussed, it reads the PSB and DBD from data sets, IMSVS.TEST1.PSBSRC and IMSVS.TEST1.DBDSRC. The JavaName parameter in the PSB statement sets the name of the generated class, and also determines the names of some of other output files. The utility generates an IMS Java class named, EmployeeView, and writes it to the HFS file, EmployeeView.java. A package statement is included in the class source to specify that the class is part of the package, example2.
| | | | |
An XMI stream describing the data view of AUTPSB5 and its databases is generated and written to the file, xmiOutput.xmi. A trace of the execution is written to the file, dlimodeltrace. The DLIModel Java Report is written to the file, EmployeeViewJavaReport.txt. Since no paths are specified for these outputs, they are all written to the default directory in the HFS file system.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
Figure 42 shows the DLIModel Java Report from this execution. It matches the generated IMS Java metadata class (not shown). DLIModel Java Report ======================== Class: EmployeeView in package: example2
generated for PSB: AUTPSB2
================================================== PCB: PCB1 ================================================== Segment: EMPL Field: EMPNO Type=CHAR Start=1 Length=6 ++ Primary Key Field ++ Field: LASTNME Type=CHAR Start=7 Length=25 (Search Field) Field: FIRSTNME Type=CHAR Start=32 Length=25 (Search Field) ================================================== Segment: DEALER Field: DLRNO2 Type=CHAR Start=1 Length=4 ++ Primary Key Field ++ Field: DLRNO Type=CHAR Start=11 Length=4 (Search Field) Field: DLRNAME Type=CHAR Start=15 Length=30 (Search Field) Field: CITY Type=CHAR Start=45 Length=10 (Search Field) ================================================== Segment: SALESINF Field: QUOTA Type=CHAR Start=1 Length=5 (Search Field) Field: SALESYTD Type=CHAR Start=7 Length=5 (Search Field) ================================================== Segment: EMPLINFO Field: STATE Type=CHAR Start=51 Length=2 ++ Primary Key Field ++ Field: ADDRESS Type=CHAR Start=1 Length=61 (Search Field) Field: STREET Type=CHAR Start=1 Length=25 (Search Field) Field: CITY Type=CHAR Start=26 Length=25 (Search Field)
| | | | | | |
Figure 42. DLIModel Java Report for Logical Relationship Example
There are three significant differences in this report as opposed to the preceding simple report shown in Figure 36 on page 79. v First, note that the layout of the DEALER segment reflects the fact that it is a concatenated segment. The first field, DLRNO2, is the destination parent
82
IMS Java User’s Guide
DLIModel Utility Examples | | | | | |
concatenated key associated with the virtual logical child, EMPSAL. Since the logical relationship is being crossed by way of this virtual logical child, its SEQ field, DLRNO2, becomes the key field of the concatenated segment. There are no other fields in the EMPSAL segment, but if there had been, they would have followed the DLRNO2 field in the report. The fields DLRNO, DLRNAME and CITY, are all fields from the destination parent, DEALER, in DEALDB2.
| | | | | | | | | |
v Second, note that the SALESINF segment has two fields, QUOTA and SALEYTD, reflecting the sensitive fields defined in the PSB. Neither is a key field, since the SALESINF segment does not have a defined sequence field in the DBD. v Finally, the EMPLINFO segment illustrates field redefinition in the DBD. The segment primary key field, STATE, appears first, as it does in the DBD. The second field listed, ADDRESS, redefines STREET and CITY, and the key field, STATE. This is indicated by the lengths and starting positions of the fields. IMS Java, the generated metadata class, and the report accommodate any redefinitions present in the FIELD definitions of the IMS DBD.
|
Example 3. Example With a Secondary Index
|
Example 3 uses the same physical DBDs as Example 2.
| | | | | | |
Note that the segment ORDER in DEALDB2 has an XDFLD statement that defines a secondary index search field, XDFLD2, and that it has an LCHILD statement that references the secondary index database, SINDEX2 (as shown in the following fragment).
| | |
The SRCH fields and the DDATA field named in the XDFLD statement all refer to fields in the ORDER segment itself, so in this example the source segment is the same as the target segment. However, this is not required by IMS Java.
| | | | | | | | | | |
The corresponding secondary index database is shown in Figure 43.
| | | | | |
LCHILD XDFLD
NAME=(SINDXA,SINDEX2),POINTER=INDX NAME=XFLD2,SRCH=(LASTNME,FIRSTNME,ORDNBR), DDATA=DATE
DBD NAME=SINDEX2,ACCESS=(INDEX,VSAM) DATASET DD1=SINDX2P SEGM NAME=SINDXA,PARENT=0,BYTES=66 FIELD NAME=(XFLDA,SEQ,U),BYTES=56,START=1,TYPE=C FIELD NAME=DATE,BYTES=10,START=57,TYPE=C LCHILD NAME=(ORDER,DEALDB2),INDEX=XFLD2 DBDGEN FINISH END
X
SEARCH DUP DATA
Figure 43. DBD for Secondary Index Example
The logical database used by this example, Figure 44 on page 84 is based on DEALDB2, and does not cross any logical relationships.
Chapter 5. DLIModel Utility
83
DLIModel Utility Examples DBD NAME=DEALLDB2,ACCESS=LOGICAL DATASET LOGICAL SEGM NAME=DEALER,PARENT=0,SOURCE=((DEALER,,DEALDB2)) SEGM NAME=MODEL,PARENT=DEALER,SOURCE=((MODEL,,DEALDB2)) SEGM NAME=ORDER,PARENT=MODEL,SOURCE=((ORDER,,DEALDB2)) DBDGEN FINISH END
| | | | | | | | | | | | | | | | | | | | |
Figure 44. Logical DBD for Secondary Index Example
The PSB is shown in Figure 45. The PROCSEQ= parameter in the PCB macro specifies a secondary processing sequence using the SINDEX2 secondary index. PCB1
| | | | | | |
PCB TYPE=DB,DBDNAME=DEALLDB2,PROCOPT=GR,KEYLEN=100, PROCSEQ=SINDEX2 SENSEG NAME=ORDER,PARENT=0 SENSEG NAME=MODEL,PARENT=ORDER SENSEG NAME=DEALER,PARENT=MODEL PSBGEN PSBNAME=AUTPSB3,LANG=ASSEM,CMPAT=YES END
X
Figure 45. PSB for Secondary Index Example
This example is intended to be run from the USS prompt, instead of via JCL, as the previous examples were. A hypothetical command line is shown in Figure 46. > java com.ibm.ims.metagen.dlimodel ./ctlfiles/ctl1
| | | | | | | | | | |
Figure 46. MVS USS Command for Secondary Index Example
The control file, ./ctlfiles/ctl1 is shown in Figure 47. Options PSBds=IMSVS.TEST1.PSBSRC DBDds=IMSVS.TEST1.DBDSRC GenJavaSource=yes Package=example3 GenXMI=yes GenTrace=yes PSB PSBName=AUTPSB3 JavaName=OrderView PCB PCBName=PCB1 JavaName=OrdersByName
| | | | |
Figure 47. Control Data Set for Secondary Index Example
In this control data set, a PCB control statement overrides the label in the IMS PCB statement (in the PSB shown in Figure 46) to a more descriptive name. The DLIModel utility generates the DLIModel Java Report in Figure 48 on page 85, together with a matching metadata class (not shown here).
| | |
84
IMS Java User’s Guide
DLIModel Utility Examples | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
DLIModel Java Report ======================== Class: OrderView in package: example3
generated for PSB: AUTPSB3
================================================== PCB: OrdersByName ================================================== Segment: ORDER Field: ORDNBR Type=CHAR Start=1 Length=6 (Search Field) Field: LASTNME Type=CHAR Start=7 Length=25 (Search Field) Field: FIRSTNME Type=CHAR Start=32 Length=25 (Search Field) Field: DATE Type=CHAR Start=57 Length=10 (Search Field) Field: XFLD2 Length=56 ++ Secondary Key Field ++ Component search fields: LASTNME. Length=25. Type=CHAR FIRSTNME. Length=25. Type=CHAR ORDNBR. Length=6. Type=CHAR ================================================== Segment: MODEL Field: MODKEY Type=CHAR Start=3 Length=24 ++ Primary Key Field ++ Field: MODTYPE Type=CHAR Start=1 Length=2 (Search Field) Field: MAKE Type=CHAR Start=3 Length=10 (Search Field) Field: MODEL Type=CHAR Start=13 Length=10 (Search Field) Field: YEAR Type=CHAR Start=23 Length=4 (Search Field) Field: MSRP Type=CHAR Start=27 Length=5 (Search Field) ================================================== Segment: DEALER Field: DLRNO Type=CHAR Start=1 Length=4 ++ Primary Key Field Field: DLRNAME Type=CHAR Start=5 Length=30 (Search Field) Field: CITY Type=CHAR Start=35 Length=10 (Search Field)
Figure 48. DLIModel Java Report for Secondary Index Example
The difference between this Java Report and preceding examples is the presence of the secondary index in the ORDER segment. Note that the ORDER segment no longer has a primary key field, but instead has a field, XDFLD2, annotated as a ++Secondary Key Field++. This field can be used in the WHERE clause of a JDBC call and will function as a primary key field, providing fast response to queries. However, it is a virtual field and it cannot be retrieved from a result set by the application.
| | | | |
In this example, where source and target segments are the same, the component search fields are also present in the ORDER segment, and so they could be retrieved as individual fields. In general, however, these fields may not be defined in the target segment, and so it would not be possible to retrieve them as individual fields.
| | | | | | |
Note also that the component search fields of the secondary index field are listed in the report under the index field description. This information is intended to help the application developer construct suitable search strings for WHERE clauses that use the index field. In this example, since the source and target segments are the same, this information is readily available from the ORDER segment definition itself. However, in general these source fields may not be defined in the target segment, and may not even be present in the Java Report.
| | | | |
Example 4. Example with Multiple Control Statements This example uses the physical database and PSB shown in Figure 49 on page 86 and Figure 50 on page 86 to illustrate the use of control statements to define additional fields and additional name and data type information. It is the same example that is used in Chapter 3, “Accessing an IMS Database” on page 23 to Chapter 5. DLIModel Utility
85
DLIModel Utility Examples describe how to access IMS databases from Java applications using JDBC. This example also illustrates how control statements might be split across more than one file.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
DBD NAME=DEALERDB,ACCESS=(HDAM,OSAM),RMNAME=(DFSHDC40.1.10) SEGM NAME=DEALER,PARENT=0,BYTES=94 FIELD NAME=(DLRNO,SEQ,U),BYTES=4,START=1,TYPE=C FIELD NAME=DLRNAME,BYTES=30,START=5,TYPE=C SEGM NAME=MODEL,PARENT=DEALER,BYTES=43 FIELD NAME=(MODTYPE,SEQ,U),BYTES=2,START=1,TYPE=C FIELD NAME=MAKE,BYTES=10,START=3,TYPE=C FIELD NAME=MODEL,BYTES=10,START=13,TYPE=C FIELD NAME=YEAR,BYTES=4,START=23,TYPE=C FIELD NAME=MSRP,BYTES=5,START=27,TYPE=P SEGM NAME=ORDER,PARENT=MODEL,BYTES=127 FIELD NAME=(ORDNBR,SEQ,U),BYTES=6,START=1,TYPE=C FIELD NAME=LASTNME,BYTES=25,START=50,TYPE=C FIELD NAME=FIRSTNME,BYTES=25,START=75,TYPE=C SEGM NAME=SALES,PARENT=MODEL,BYTES=113 FIELD NAME=(SALDATE,SEQ,U),BYTES=8,START=1,TYPE=C FIELD NAME=LASTNME,BYTES=25,START=9,TYPE=C FIELD NAME=FIRSTNME,BYTES=25,START=34,TYPE=C FIELD NAME=STKVIN,BYTES=20,START=94,TYPE=C SEGM NAME=STOCK,PARENT=MODEL,BYTES=62 FIELD NAME=(STKVIN,SEQ,U),BYTES=20,START=1,TYPE=C FIELD NAME=COLOR,BYTES=10,START=37,TYPE=C FIELD NAME=PRICE,BYTES=5,START=47,TYPE=C FIELD NAME=LOT,BYTES=10,START=53,TYPE=C DBDGEN FINISH END
| | | | | | | | | | | |
Figure 49. Physical DBD for Multiple Control Statements Example
DLR_PCB1 PCB SENSEG SENSEG SENSEG SENSEG SENSEG PSBGEN END
| | | | | |
TYPE=DB,DBDNAME=DEALERDB,PROCOPT=GO,KEYLEN=42 NAME=DEALER,PARENT=0 NAME=MODEL,PARENT=DEALER NAME=ORDER,PARENT=MODEL NAME=SALES,PARENT=MODEL NAME=STOCK,PARENT=MODEL PSBNAME=DLR_PSB,MAXQ=200
Figure 50. PSB for Multiple Control Statements Example
The example is executed from the MVS USS prompt, as shown in Figure 51. > java com.ibm.ims.metagen.dlimodel ./ctlfiles/ctl4
| | | | |
Figure 51. MVS USS Command for Control Statements Example
The top-level control statement file, ctl4, is shown in Figure 52 on page 87.
86
IMS Java User’s Guide
DLIModel Utility Examples | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
OPTIONS
PSBds=IMSVS.TEST1.PSBSRC DBDds=IMSVS.TEST1.DBDSRC GenJavaSource=YES gentrace=yes outpath=gen Package=com.ibm.ims.tooling
PSB psbName=DLR_PSB JavaName=DealerDatabaseView PCB PCBName=DLR_PCB1 JavaName=DealershipDB Include Dataset=tests.samp.ctl/cntrstmt2
Figure 52. Top-Level Control Data Set for Multiple Control Statements Example
This control file establishes the options for the execution, as in previous examples, and directs the outputs (generated classes, java report, and trace) to a specified directory (outpath=gen). It also names the PSB to be processed, assigns a Java name for the generated class for this PSB, and provides a Java name for a PCB in that PSB. Unlike previous examples, this example includes a second-level control statement file, called cntrstmt2, which is shown in Figure 53 on page 88. This control file provides details of additional fields in the segments of the database referenced from DLR_PCB1, and additional information about existing fields in that database. Note two facts about this second control statement file: v The information it contains is only necessary because there are additional facts about the segments in this database that are needed by this (hypothetical) Java application. If your DBD names all the fields that are used by your application, and if all the fields can be treated as CHAR data type, and if your application can use the standard 8-character names, then you would not need to supply SEGM or Field control statements. v The Segment and Field control statements need only be split off into a second file if it is convenient to do so, perhaps because this additional segment information needs to be shared by other applications. In such cases you might group all field information for a whole database (as is shown in Figure 53 on page 88) or for each segment into its own file. If this is not advantageous for your data, it is equally acceptable to place all control statements in a single, top-level file.
|
Chapter 5. DLIModel Utility
87
DLIModel Utility Examples | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
SEGM DBDName=DEALERDB SegmentName=DEALER JavaName=DEALERXX FIELD Name=DLRNO Start=1 Bytes=4 JavaType=CHAR FIELD Start=5 Bytes=30 JavaType=CHAR FIELD Start=35 Bytes=50 JavaType=CHAR FIELD Start=85 Bytes=10 JavaType=PACKEDDECIMAL TypeQualifier=S9(18)
JavaName=DealerNumber JavaName=DealerName JavaName=DealerAddress JavaName=YTDSales
SEGM DBDName=DEALERDB SegmentName=MODEL JavaName=MODELXX FIELD Name=MODTYPE Start=1 Bytes=2 JavaType=CHAR JavaName=ModelTypeCode FIELD Name=MAKE Start=3 Bytes=10 JavaType=CHAR JavaName=CarMake FIELD Name=MODEL Start=13 Bytes=10 JavaType=CHAR JavaName=CarModel FIELD Name=YEAR Start=23 Bytes=4 JavaType=CHAR JavaName=CarYear FIELD Name=MSRP Start=27 Bytes=5 JavaType=CHAR JavaName=Price FIELD Start=32 Bytes=4 JavaType=CHAR JavaName=EPACityMilage FIELD Start=36 Bytes=4 JavaType=CHAR JavaName=EPAHighwayMilage FIELD Start=40 Bytes=4 JavaType=CHAR JavaName=Horsepower SEGM DBDName=DEALERDB FIELD Name=ORDNBR FIELD FIELD FIELD FIELD Name=LASTNME FIELD Name=FIRSTNME FIELD FIELD
SegmentName=ORDER JavaName=ORDERXX Start=1 Bytes=6 JavaType=CHAR JavaName=OrderNumber Start=7 Bytes=30 JavaType=CHAR JavaName=Options Start=37 Bytes=5 JavaType=ZONEDDECIMAL TypeQualifier=99999 JavaName=Price Start=42 Bytes=8 JavaType=CHAR JavaName=OrderDate Start=50 Bytes=25 JavaType=CHAR JavaName=PurchaserLastName Start=75 Bytes=25 JavaType=CHAR JavaName=PurchaserFirstName Start=100 Bytes=8 JavaType=CHAR JavaName=SerialNo Start=120 Bytes=8 JavaType=CHAR JavaName=DeliverDate
SEGM DBDName=DEALERDB FIELD Name=SALDATE FIELD Name=LASTNME FIELD Name=FIRSTNME FIELD FIELD FIELD Name=STKVIN
SegmentName=SALES Start=1 Bytes=8 Start=9 Bytes=25 Start=34 Bytes=25 Start=59 Bytes=25 Start=84 Bytes=10 Start=94 Bytes=20
JavaName=SALESXX JavaType=CHAR JavaName=DateSold JavaType=CHAR JavaName=PurchaserLastName JavaType=CHAR JavaName=PurchasetFirstName JavaType=CHAR JavaName=PurchaserAddress JavaType=CHAR JavaName=SoldBy JavaType=CHAR JavaName=StockVINumber
SEGM DBDName=DEALERDB SegmentName=STOCK JavaName=STOCKXX FIELD Name=STKVIN Start=1 Bytes=20 JavaType=CHAR FIELD Start=21 Bytes=8 JavaType=CHAR FIELD Start=29 Bytes=8 JavaType=CHAR FIELD Name=COLOR Start=37 Bytes=10 JavaType=CHAR FIELD Name=PRICE Start=47 Bytes=5 JavaType=ZONEDDECIMAL TypeQualifier=99999 FIELD Name=LOT Start=53 Bytes=10 JavaType=CHAR
JavaName=StockVINumber JavaName=DateIn JavaName=DateOut JavaName=Color JavaName=Price JavaName=Lot
| | Figure 53. Second-Level Control Data Set for Multiple Control Statements Example | Under the SEGM statement for DEALER, the first Field statement identifies an | existing field, DLRNO, by both its DBD name and its start position and length. | These facts will be checked for consistency against the DBD. If the field is identified | correctly, then it is assigned a Java name, DealerNumber, and a data type, CHAR | (which is the default, and therefore not necessary to specify). | | | | | |
The second Field statement identifies an existing field by only its start position and length. If such a field exists, it is assigned the Java name, DealerName. This abbreviated method of identifying the field achieves the same result, but is not quite so safe because no 8-character name check is carried out. The data type for DealerName default is CHAR.
| | | |
The third Field statement under the DEALER SEGM statement defines a new field -- a field that is physically present in the segment, but is not described by a FIELD macro in the DBD. It specifies the start position and length of this field, assigns it a Java name of DealerAddress, and a type of CHAR.
88
IMS Java User’s Guide
DLIModel Utility Examples | | |
The fourth Field statement defines another new field, YTDSales, of type PACKEDDECIMAL. This data type requires a type qualifier that defines the field format, and in this example, a qualifier of S9(18) is supplied.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
The remainder of the control statements describe information for the other segments and fields in the DBD in a similar manner. When DLIModel is executed, it generates the DLIModel Java Report in Figure 23, together with a matching metadata class (not shown here). DLIModel Java Report ======================== Class: DealerDatabaseView
generated for PSB: DLR_PSB
================================================== PCB: DealershipDB ================================================== Segment: DEALERxx Field: DealerNumber Type=CHAR Start=1 Length=4 ++ Primary Key Field ++ Field: DealerName Type=CHAR Start=5 Length=30 (Search Field) Field: DealerAddress Type=CHAR Start=35 Length=50 Field: YTDSales Type=PACKEDDECIMAL Type Qualifier=S9(18) Start=85 Length=10 ================================================== Segment: MODELXX Field: ModelTypeCode Type=CHAR Start=1 Length=2 ++ Primary Key Field ++ Field: CarMake Type=CHAR Start=3 Length=10 (Search Field) Field: CarModel Type=CHAR Start=13 Length=10 (Search Field) Field: CarYear Type=CHAR Start=23 Length=4 (Search Field) Field: Price Type=CHAR Start=27 Length=5 (Search Field) Field: EPACityMilage Type=CHAR Start=32 Length=4 Field: EPAHighwayMilage Type=CHAR Start=36 Length=4 Field: Horsepower Type=CHAR Start=40 Length=4 ================================================== Segment: ORDERXX Field: OrderNumber Type=CHAR Start=1 Length=6 ++ Primary Key Field ++ Field: PurchaserLastName Type=CHAR Start=50 Length=25 (Search Field) Field: PurchaserFirstName Type=CHAR Start=75 Length=25 (Search Field) Field: Options Type=CHAR Start=7 Length=30 Field: Price Type=ZONEDDECIMAL Type Qualifier=99999 Start=37 Length=5 Field: OrderDate Type=CHAR Start=42 Length=8 Field: SerialNo Type=CHAR Start=100 Length=8 Field: DeliverDate Type=CHAR Start=120 Length=8 ================================================== Segment: SALESXX Field: DateSold Type=CHAR Start=1 Length=8 ++ Primary Key Field ++ Field: PurchaserLastName Type=CHAR Start=9 Length=25 (Search Field) Field: PurchasetFirstName Type=CHAR Start=34 Length=25 (Search Field) Field: StockVINumber Type=CHAR Start=94 Length=20 (Search Field) Field: PurchaserAddress Type=CHAR Start=59 Length=25 Field: SoldBy Type=CHAR Start=84 Length=10 ================================================== Segment: STOCKXX Field: StockVINumber Type=CHAR Start=1 Length=20 Field: Color Type=CHAR Start=37 Length=10 Field: Price Type=CHAR Start=47 Length=5 Field: Lot Type=CHAR Start=53 Length=10 Field: DateIn Type=CHAR Start=21 Length=8 Field: DateOut Type=CHAR Start=29 Length=8
++ Primary (Search (Search (Search
Key Field ++ Field) Field) Field)
| | Figure 54. DLIModel Java Report for Multiple Control Statements Example | | In this DLIModel Java Report, the names of segments and fields are the Java | names supplied in the control statements. The eight-character IMS names do not | appear because the Java developer does not need to know these names. Chapter 5. DLIModel Utility
89
DLIModel Utility Examples
90
IMS Java User’s Guide
Chapter 6. Problem Determination This chapter contains information on debugging your IMS Java programs and determining the source of problems within your IMS Java programs. In this Chapter: v “Exceptions” v “Sync Point Failure” on page 93 v “GU Message Failure” on page 93 v “Abends” on page 93 v “DLIModel Messages” on page 94 v “IMSTrace” on page 96
Exceptions Exceptions are thrown as a result of non-blank status codes and non-zero return codes (in cases when there were no PCBs to deliver status codes) from IMS DL/I calls. Even though an exception is thrown by JavaToDLI for every non-blank status code, some of these exceptions are caught by the application or database packages and converted to return values.
How Exceptions Map to DL/I Status Codes IMSException extends java.lang.Exception. DLIException extends IMSException. Exceptions of this type include all errors that occur within the IMS Java library and are not a result of any call to IMS. You can use the following methods to extract information from an IMSException: getAIB Returns the IMS AIB from the DL/I call that caused the exception. IMS AIB is null for DLIException. The methods on the AIB can be called to return other information at the time of the failure, including the resource or PCB name and the PCB itself. | | |
getStatusCode Returns the IMS status code from the DL/I call that caused the exception. This method works with the JavaToDLI set of constants. The status code is zero (0) for a DLIException. getFunction Returns the IMS function from the DL/I call that caused the exception. Function is zero (0) for a DLIException.
| | | | |
The database access methods of DLIConnection in Figure 55 on page 92 return false if they receive GB (no more such segments or segment not found) or GE (no such segment or end of database) status codes and they are consumed by DLIConnection.
© Copyright IBM Corp. 2000, 2002
91
Exceptions DLIConnection.getUniqueSegment DLIConnection.getNextSegment DLIConnection.getUniqueRecord DLIConnection.getNextRecord DLIConnection.getNextSegmentInParent
Figure 55. Database access methods of DLIConnection
The IMSMessageQueue.getUniqueMessage method returns false if it receives a QC (no more messages) status code. The IMSMessageQueue.getNextMessage method returns false if it receives a QD (no more segments [for multi-segment messages]) status code. These exceptions are consumed by IMSMessageQueue. Figure 56 shows an example of extracting information from an IMSException: try { DealerDatabaseView dealerView = new DealerDatabaseView(); DLIConnection connection = DLIConnection.createInstance(dealerView); connection.getUniqueSegment(dealerSegment, dealerSSAList); } catch (IMSException e ) { short statusCode = e.getStatusCode(); String failingFunction = e.getFunction(); }
Figure 56. IMSException Sample
Related Reading: For more information on DL/I Status Codes see IMS Version 7 Application Programming: Database Managerand IMS Version 7 Application Programming: Transaction Manager.
SQLExceptions SQLException is thrown to indicate that an error has occurred either in the Java address space or during database processing. Each SQLException provides the following information: v A string describing the error. – This string is available through the use of the getMessage() method. v An “SQLstate” string that follows XOPEN SQLstate conventions.
|
– The values of the SQLstate string are described in the XOPEN SQL specification. v A link to the next SQL exception if more than one was generated . – The next exception is used as a source of additional error information.
92
IMS Java User’s Guide
Sync Point Failure
Sync Point Failure If you receive an SY DL/I PCB status code, your IMS Java application SYNC request call has failed. Table 6 describes the failure. Table 6. Status Code, Reason, and Return Code DL/I Return/ Reason Code 0108/ 056C
PCB Status Code SY
System Service Call IMS Java sync
Category
5
Description
Internal error during sync point processing for an IMS Java application. Sync point failure. AIBERRXT contains the SYNC return code.
A call to the sync point processor (DFSTMS00) returned a non-zero return code. Contact your IMS system programmer. |
GU Message Failure
| | |
If you receive a CR DL/I PCB status code, your IMS Java application GU message request call has failed. Table 7 describes the failure. Correct your application to issue a Java commit prior to issuing your next GU message call.
|
Table 7. Status Code, Reason, and Return Code
| | | |
AIB Return/ Reason Code
| | |
0104/ 0300
PCB Status Code CR
System Service Call IMS Java GU Message
Category
4
Description
Application error during GU message processing for an IMS Java application.
Abends An abend is the abnormal ending of a program or application. When an abend error condition occurs, an abend macro is issued either at the point of error detection or by branching to a routine that issues the abend macro. There are also pseudoabends in which the module that detects the error condition does not issue the abend macro. Instead, it passes control back to the IMS call analyzer module, DFSDLA00, which writes the contents of important control blocks to the system log and indicates a dependent-region abend. Following are the abends that you might encounter as a result of errors while running IMS Java applications.
ABENDU0118 - Commit Failure | | |
This abend is issued if your IMS Java application attempts to terminate without calling IMSTransaction.commit. An explicit commit is required for each IMS Java application before it can terminate normally. Related Reading: For more information on ABENDU0118, see IMS Version 7 Failure Analysis Structure Tables (FAST) for Dump Analysis and IMS Version 7 Messages and Codes, Volume 1.
Chapter 6. Problem Determination
93
Sync Point Failure
ABENDU0475 - Batch Run Failure This abend is issued if your IMS Java application attempts to run as an IMS Batch job. IMS batch does not currently support IMS Java applications. Related Reading: For more information on ABENDU0475, see IMS Version 7 Failure Analysis Structure Tables (FAST) for Dump Analysis, and IMS Version 7 Messages and Codes, Volume 2.
Processing Dumps You might be asked to help interpret a dump for diagnostic purposes. Related Reading: v For more information on dump processing, see IMS Version 7 Installation Volume 2: System Definition and Tailoring and IMS Version 7 Utilities Reference: Database and Transaction Manager. v For more information on dump analysis, see IMS Version 7 Failure Analysis Structure Tables (FAST) for Dump Analysis and the IMS Version 7 Diagnosis Guide and Reference. |
DLIModel Messages
|
This section describes the messages that are issued by the DLIModel utility.
| |
The DLIModel utility message number severity suffixes are as follows unless otherwise indicated:
|
E
Unrecoverable error
|
W
Warning
|
I
Informational message
| | DHM0001 |
System Error: text (class/method) (DHM0001E)
| | |
Explanation: This message describes a probable error in the DLIModel utility during the import of a PSB or DBD.
|
text
| | |
(class/method) -describes the location; class or method name, in DLIModel at which the error was detected
| |
(DHM00001E) -the message reference number
| | | | | | |
Programmer Response: Call IBM for service. Have these things available:
| | |
Problem Determination: You may be asked to rerun DLIModel with the option parameter, Trace=yes set in order to aid in the problem determination.
v
-describes the problem
the content of this message
v the input PSBs and all related DBDs v control statement data set or file v the JCL or USS command that you used to execute the utility
94
IMS Java User’s Guide
| | DHM0002 through DHM0199 text (class/method) (DHM0xxxE) | | | | |
Explanation: Messages in this range describe problems in the input data that prevent the utility from continuing during the import of a PSB or DBD. As a result, the utility terminates.
| text
-describes the problem
| (class/method) -describes the location; class or method name, | in DLIModel at which the error was detected | | (DHM0xxxE) -the message reference number | | | | | | | | | |
xxx
the last three digits of the message number, in the range: 2 through 199
Programmer Response: Typically, this error is the result of incorrect or inconsistent PSB or DBD source data. It is strongly recommended that PSBs and DBDs are compiled, an ACBGEN is performed, and all errors are corrected before running the DLIModel utility. If these tasks are not done, there is no guarantee that the DLIModel utility will detect all potential errors in the PSB
DLIModel Messages | or DBD source, so the resulting output might be | incomplete or incorrect. | | | | | | | | |
If the PSBs and the DBDs have been validated (through PSBGEN, DBDGEN, and ACBGEN) but the problem persists, call IBM for service. Have these things available: v the content of this message v the input PSBs and DBDs v the control statement data set or file v the JCL or USS command that you used to execute the utility
| Problem Determination: You may be asked to rerun | DLIModel with the option parameter, Trace=yes set in | order to aid in the problem determination. | | DHM0200 through DHM0299 | | | | |
text (DHM02xxW)
Explanation: These messages describe warnings of problems with the input data that did not prevent the DLIModel utility from continuing. In most cases part of the input data is ignored in order to circumvent the problem, and this might result in incomplete output.
| text
-describes the problem
| (DHM02xxW) -the message reference number | | | | | | | | | | | | |
xx
the last two digits of the message number, in the range: 0 through 99
Programmer Response: The utility output (for example the IMS Java metadata classes) should be carefully reviewed before use. In some cases the output will be usable after one of these warnings -- for example, a PSB may contain a PCB that references an MSDB type database, which cannot be handled by the utility. The generated IMS Java classes report of the XMI file will omit the MSDB database, that would typically be acceptable for an IMS Java application that used the metadata classes.
| | DHM0500 through DHM0599 text (DHM05xxy) | Explanation: These messages describe standard | actions taken, warnings, and errors that occur during | the processing of the DLIModel control statement file. | text
-describes the problem
| (DHM05xxy) -the message reference number | | |
xx
the last two digits of the message number, in the range: 0 through 99
|
y
one of these severities:
|
I
informational
|
W
warning
|
E
error
| Programmer Response: | Informational messages: Confirm that the action that was performed by | the utility is acceptable. | | Warning messages: These messages describe an error that could | be corrected or ignored by the utility, allowing it | to continue,. Frequently this is done by ignoring | part of one or more control statements. | | | | |
Confirm that the action that was performed by the utility is acceptable by reviewing the message and the generated output. Correct and rerun the utility if necessary.
| Error messages: These messages describe an error that caused | the utility to terminate. Correct the error and | rerun the utility. In some cases, one of these | messages is followed by related messages that | describe a system error, or an error or a | warning regarding input data. | | | DHM0800W through DHM0899W text (DHM008xxE) | Explanation: These messages describe errors that | occur during the export of the IMS Java metadata | classes and the Java report. | text
-describes the problem
| (DHM08xxE) -the message reference number | | |
xx
the last two digits of the message number, in the range: 0 through 99
| | | | | | |
Programmer Response: Message DHM0800E describes problems that are probable system errors. Call IBM for service. Have the following things available: the content of this message, the input PSB and all related DBDs, control statement data set or file, and the JCL or USS command that was used to execute the utility
| | | | | | | | |
Other messages in this range are often caused by incorrect or inconsistent PSB or DBD source data. It is strongly recommended that PSBs and DBDs be compiled, an ACBGEN performed, and all errors corrected before running the DLIModel utility. If these tasks are not done, there is no guarantee that the DLIModel utility will detect all potential errors in the PSB or DBD source, and the export of IMS Java entities may fail, resulting in one of these messages.
| | | | | | |
If the PSBs and the DBDs have been validated (through PSBGEN, DBDGEN, and ACBGEN) but the problem persists, call IBM for service. Have these things available: v the content of this message v the input PSBs and DBDs v the control statement data set or file
Chapter 6. Problem Determination
95
DLIModel Messages | v the JCL or USS command that you used to execute the utility |
| |
DLIModel with the option parameter, Trace=yes set in order to aid in the problem determination.
| Problem Determination: You may be asked to rerun |
IMSTrace With IMSTrace, you can debug your Java applications by tracing, or documenting, the flow of control throughout your application. By setting up tracepoints throughout your applications for output, you can isolate problem areas and, therefore, know where to make adjustments to produce the results you expect. In addition, because IMSTrace supports writing input parameters and results, and the IMS-Java-library-provided routines use this feature, you can verify that correct results occur across method boundaries. IMSTrace is distinct from the DLIModel utility trace. For information on how to set the DLIModel utility trace, see “OPTIONS Statement” on page 68.
Initiating IMSTracing To debug with IMSTrace, you must first turn on the tracing function by setting the IMSTrace.traceOn variable to true. Because tracing does not occur until this variable is set, it is best to do so within a static block of your main application class. Then, you must decide how closely you want to trace the IMS Java library’s flow of control, and how much tracing you want to add to your application code.
| | | | |
You determine the amount of tracing in the IMS Java library by setting the value of IMSTrace.libTraceLevel to one of its predefined values. By default, this value is set to IMSTrace.TRACE_EXCEPTIONS, which traces the construction of IMS-Java-library-provided exceptions. IMSTrace also defines constants for three types of additional tracing. These constants provide successively more tracing from IMSTrace.TRACE_CTOR1 (level one tracing of constructions) to IMSTrace.TRACE_DATA3 (level three tracing of data).
Setting up Tracing for the IMS Java Library Routines | | | | | | | | | | | | |
To turn on the tracing shipped with the IMS Java Library Routines: 1. Turn on the flag enabling tracing (it is turned off by default):
| | |
These steps are best implemented within a static method of your main class, as shown in Figure 57 on page 97:
IMSTrace.traceOn = true;
2. Set the level of tracing for the IMS Java Library Routines. In this example, constructors and the entry and exit of level one methods are traced: IMSTrace.libTraceLevel = IMSTrace.TRACE_METHOD1;
3. Set an output stream (a print stream or a character output writer) as the current trace stream. For example: a. Set the system error stream as the current trace stream: IMSTrace.setOutputStream(System.err);
b. Set a StringWriter (an in-memory buffer) as the current trace stream: StringWriter stringWriter = new StringWriter(); IMSTrace.setOutputWriter(stringWriter);
96
IMS Java User’s Guide
IMSTrace public class IMSAuto extends IMSApplication { static { IMSTrace.traceOn = true; IMSTrace.libTraceLevel = IMSTrace.TRACE_METHOD1; IMSTrace.setOutputStream(System.err); } public static void main(String args[]){ IMSAuto application = new IMSAuto(); application.begin(); } }
Figure 57. Setting a Trace within a Static Method
Adding Trace Statements to Your Application You can add trace statements to your application, similar to those provided by the IMS Java Library, by defining an integer variable that you test prior to writing trace statements. Using a variable other than IMSTrace.libTraceLevel enables you to control the level of tracing in your application independently of the tracing in the IMS Java library. For example, you can turn off the tracing of IMS Java Library routines by setting IMSTrace.libTraceLevel to zero but still trace your application code. Follow these steps to add tracing to your application code: 1. Define an integer variable to contain the trace level for application-provided code: public class IMSAuto extends IMSApplication { public int applicationTraceLevel = IMSTrace.TRACE_CTOR3;
2. Set up IMSTrace to trace methods, parameters, and return values as necessary, as shown in Figure 58: public class IMSAuto extends IMSApplication { public static int applicationTraceLevel=IMSTrace.TRACE_CTOR3; static { IMSTrace.traceOn = true; IMSTrace.libTraceLevel = IMSTrace.TRACE_METHOD1; IMSTrace.setOutputStream(System.err); } public static void main (String args[]) { IMSAuto application = new IMSAuto(); application.begin(); }
Figure 58. Setting Up IMSTrace (Part 1 of 3)
Chapter 6. Problem Determination
97
IMSTrace public void doBegin() throws IMSException { if (IMSAuto.applicationTraceLevel >= IMSTrace.TRACE_METHOD1) IMSTrace.currentTrace().logEntry("IMSAuto.doBegin"); try { //Add code here . . . } finally { if (IMSAuto.applicationTraceLevel >= IMSTrace.TRACE_METHOD1) IMSTrace.currentTrace().logExit("IMSAuto.doBegin"); } } public String method1(String parm1){ if (IMSAuto.applicationTraceLevel >= IMSTrace.TRACE_METHOD2) { IMSTrace.currentTrace().logEntry("IMSAuto.method1"); if (IMSAuto.applicationTraceLevel >= IMSTrace.TRACE_DATA2) IMSTrace.currentTrace().logParm("parm1", parm1); } String result = new String(); try { //Add code here . . . result = "result"; }
Figure 58. Setting Up IMSTrace (Part 2 of 3)
finally { if (IMSAuto.applicationTraceLevel >= IMSTrace.TRACE_METHOD2) IMSTrace.currentTrace().logExit("IMSAuto.method1"); } return result; }
Figure 58. Setting Up IMSTrace (Part 3 of 3)
98
IMS Java User’s Guide
| |
Appendix A. Manually Creating IMS Java Metadata Classes
| |
This appendix describes the procedure for manually creating the metadata classes required for JDBC access to IMS databases.
| |
Note: The recommended method for creating these classes is to use the DLIModel utility, described in Chapter 5, “DLIModel Utility” on page 61.
| | | | | | |
Mapping an IMS Database in Java Classes To map an IMS database in Java classes, you use the segments and fields in the Database Definition (DBD) to create DLIDatabaseView and DLISegment subclasses. The hierarchical database shown in Figure 59 is used as the sample database in the code examples that follow.
Figure 59. Example Database and Segments
| | | | | |
IMS Database Definition (DBD) The Database Definition (DBD) is set up by the database administrator. A DBD defines the segments (″SEGM NAME″) and key fields (″FIELD NAME″) of the database. Figure 60 on page 100 is the DBD for the sample hierarchical database in Figure 59.
Adding Default Values for Fields of a Segment
| | | | |
In certain cases, you might want to assign a default value for a particular Field of a Segment definition. You may want the defaults, for example, when assigning values that may not be set in the application, or for reducing the amount of required application setup for insert segment calls. To assign an initial default value manually modify the constructor for the generated DLIDatabaseView subclass.
| | | |
After the super() and any addDatabase() calls in the generated DLIDatabaseView subclass, a setString(), setInt(), or any setXXX() call can be made to set the default value. This default value remains constant throughout the application and so will exist in all cloned instances of the Segment.
| |
The following example demonstrates how to add a default value of Chris to the PersonalHero Field of the Employee Segment:
© Copyright IBM Corp. 2000, 2002
99
static DLITypeInfo[] PCB1EMPLOYEEArray= { new DLITypeInfo("LastName", DLITypeInfo.CHAR, 1, 25, "LASTNME"), new DLITypeInfo("FirstName", DLITypeInfo.CHAR, 26, 25, "FIRSTNME") new DLITypeInfo("PersonalHero", DLITypeInfo.CHAR, 51, 25, "HERO"), }; static DLISegment PCB1EMPLOYEESegment= new DLISegment ("EmployeeSegment","EMPLOYEE",PCB1EMPLOYEEArray,76);
| | | | | | | | | | | | | | | | | | | | |
//Constructor public EmpPSB1DatabaseView() { super("EMPPSB1", "pcb1", "PCB1", PCB1array); addDatabase("pcb2", "PCB2", PCB2array); // Set Default PCB1EMPLOYEESegment.setString("PersonalHero", "Chris"); } try { // Set Default ... } catch (com.ibm.ims.db.DLIException e) { throw new RuntimeException(e.toString()); }
Mapping the PSB to DLIDatabaseView
| | |
The PSB (Program Status Block) defines a grouping of resources available to an application. Included in the PSB is a DB PCB (Database Program Communication Block) definition for each database that your application can access.
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
The DB PCB defines the access rights that your application has to the segments of the database. In particular, a database PCB (PCB Type=DB) defines which segments, and which fields within those segments, your program can access, and the access intent (such as get, insert, replace, delete, or all) and isolation level (such as dirty read) that is used when accessing a database by way of that PCB. DBD NAME=DEALERDB,ACCESS=(HDAM,OSAM),RMNAME=(DFSHDC40.1.10) SEGM NAME=DEALER,PARENT=0,BYTES=94, FIELD NAME=(DLRNO,SEQ,U),BYTES=4,START=1,TYPE=C FIELD NAME=DLRNAME,BYTES=30,START=5,TYPE=C SEGM NAME=MODEL,PARENT=DEALER,BYTES=43 FIELD NAME=(MODTYPE,SEQ,U),BYTES=2,START=1,TYPE=C FIELD NAME=MAKE,BYTES=10,START=3,TYPE=C FIELD NAME=MODEL,BYTES=10,START=13,TYPE=C FIELD NAME=YEAR,BYTES=4,START=23,TYPE=C FIELD NAME=MSRP,BYTES=5,START=27,TYPE=P SEGM NAME=ORDER,PARENT=MODEL,BYTES=127 FIELD NAME=(ORDNBR,SEQ,U),BYTES=6,START=1,TYPE=C FIELD NAME=LASTNME,BYTES=25,START=50,TYPE=C FIELD NAME=FIRSTNME,BYTES=25,START=75,TYPE=C SEGM NAME=SALES,PARENT=MODEL,BYTES=113 FIELD NAME=(SALDATE,SEQ,U),BYTES=8,START=1,TYPE=C FIELD NAME=LASTNME,BYTES=25,START=9,TYPE=C FIELD NAME=FIRSTNME,BYTES=25,START=34,TYPE=C FIELD NAME=STKVIN,BYTES=20,START=94,TYPE=C SEGM NAME=STOCK,PARENT=MODEL,BYTES=62 FIELD NAME=(STKVIN,SEQ,U),BYTES=20,START=1,TYPE=C FIELD NAME=COLOR,BYTES=10,START=37,TYPE=C FIELD NAME=PRICE,BYTES=5,START=47,TYPE=C FIELD NAME=LOT,BYTES=10,START=53,TYPE=C DBDGEN FINISH END
| | |
Figure 60. DBD Sample Definition
100
IMS Java User’s Guide
| | | | | |
You define the information that is needed to connect to one or more databases from within an application with the DLIDatabaseView. In IMS Java, the DLIDatabaseView class contains metadata (information describing the data in the database, such as types and lengths of fields) that describes your application’s view of the databases that it uses. The DLIDatabaseView class includes the PSB name and any PCBs, segments, and fields that are used by the application.
| | | | | | | | | |
The DLIDatabaseView subclass contains information from both the PSB and the DBD, including the following information: v The PSBNAME from the PSBGEN macro of the PSB definition v The PCB names of any PCB macros in the PSB definition v The segments defined for a PCB using the SENSEG macro of the PSB definition. v The fields defined within a segment. These are usually defined only within the DBD, but their use may be restricted by the SENFLD macro in the PSB definition. Figure 61 on page 102 shows the PSB definition for the Dealership application.
| | | | | | | | | | | | | | | | | | |
DLIDatabaseView Example Using information from the PSB shown in Figure 61 on page 102, create a DLIDatabaseView subclass called DealerDatabaseView. The numbers in the following list (for example, 1) are referenced in Figure 61 on page 102. Note the following: v Within the subclass you create an array of DLISegmentInfo objects, one entry for each DLISegment object used by the application. 1 As you will see in “DLISegment Example” on page 103, a DLISegment object defines the fields in a database segment similar to the way an IMSFieldMessage object defines the fields in a message segment. v Each DLISegmentInfo object associates a DLISegment object to its parent. 2 The parent is specified as a zero-based index in the array. Notice that the entry for the Order segment specifies an index of 1, which is the index in the array for the Model segment. v The parent of the root segment, Dealer, is specified by the constant DLIDatabaseView.ROOT to indicate that it has no parent. 3 v The dealer PSB name, DLR_PSB, is passed in the DealerDatabaseView constructor to the super class constructor along with the array of DLISegmentInfo objects. 4
|
Appendix A. Manually Creating IMS Java Metadata Classes
101
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | 102
import com.ibm.ims.db.*; import com.ibm.ims.base.*; public class DealerDatabaseView extends DLIDatabaseView { static DLITypeInfo[] dealerInfo = { new DLITypeInfo("DealerNo",DLITypeInfo.CHAR, 1, 4, "DLRNO"), new DLITypeInfo("DealerName",DLITypeInfo.CHAR, 5, 30, "DLRNAME"), new DLITypeInfo("DealerCity",DLITypeInfo.CHAR, 35, 10, "CITY"), new DLITypeInfo("DealerZip",DLITypeInfo.CHAR, 45, 10, "ZIP"), new DLITypeInfo("DealerPhone",DLITypeInfo.CHAR, 55, 7, "PHONE"), }; static DLISegment dealerSegment = new DLISegment("DealerSegment", "DEALER", dealerInfo, 61); // An array of DLITypeInfo objects to describe fields follows: static DLITypeInfo[] modelInfo = { new DLITypeInfo("ModelType",DLITypeInfo.CHAR, 1, 2, "MODTYPE"), new DLITypeInfo("ModKey",DLITypeInfo.CHAR, 3, 24, "MODKEY"), new DLITypeInfo("Make",DLITypeInfo.CHAR, 3, 10, "MAKE"), new DLITypeInfo("Model",DLITypeInfo.CHAR, 13, 10, "MODEL"), new DLITypeInfo("Year",DLITypeInfo.CHAR, 23, 4, "YEAR"), new DLITypeInfo("MSRP",DLITypeInfo.CHAR, 27, 5, "MSRP"), new DLITypeInfo("Count",DLITypeInfo.CHAR, 32, 2, "COUNT"), }; static DLISegment modelSegment = new DLISegment("ModelSegment", "MODEL", modelInfo, 37); // An array of DLITypeInfo objects to describe fields follows: static DLITypeInfo[] orderInfo = { new DLITypeInfo("OrderNo", DLITypeInfo.CHAR, 1, 6, "ORDNBR"), new DLITypeInfo("LastName", DLITypeInfo.CHAR, 7, 25,"LASTNME") new DLITypeInfo("FirstName", DLITypeInfo.CHAR, 32, 25,"FIRSTNME"), new DLITypeInfo("Date", DLITypeInfo.CHAR, 57, 10, "DATE"), new DLITypeInfo("Time", DLITypeInfo.CHAR, 67, 8, "TIME"), }; static DLISegment orderSegment = new DLISegment("OrderSegment", "ORDER", orderInfo, 74); // An array of DLITypeInfo objects to describe fields follows: static DLITypeInfo[] salesInfo = { new DLITypeInfo("SaleNo", DLITypeInfo.CHAR, 1, 4, "SALENUM"), new DLITypeInfo("SaleDate", DLITypeInfo.CHAR, 5, 8, "SALDATE"), new DLITypeInfo("LastName", DLITypeInfo.CHAR, 13, 25, "LASTNME"), }; static DLISegment salesSegment = new DLISegment("SalesSegment", "SALES", salesInfo, 37); static DLITypeInfo[] stockInfo = { new DLITypeInfo("StockVin", DLITypeInfo.CHAR, 1, 20, "STKVIN"), new DLITypeInfo("Color", DLITypeInfo.CHAR, 21, 10, "COLOR"), new DLITypeInfo("Price", DLITypeInfo.CHAR, 31, 5, "PRICE"), new DLITypeInfo("Lot", DLITypeInfo.CHAR, 36, 10, "LOT"), new DLITypeInfo("Warranty", DLITypeInfo.CHAR, 46, 1, "WRNTY"), }; static DLISegment stockSegment = new DLISegment("StockSegment", "STOCK", stockInfo, 46); // An array of DLISegment objects to describe PSB view static DLISegmentInfo[] segments = { 1 new DLISegmentInfo(dealerSegment, DLIDatabaseView.ROOT), 3 new DLISegmentInfo(modelSegment, 0), new DLISegmentInfo(OrderSegment, 1), 2 new DLISegmentInfo(salesSegment, 1), new DLISegmentInfo(stockSegment, 1), }; public DealerDatabaseView() { super("DLR_PSB", "DealerDB", "DLR_PCB1", segments); 4 } }
Figure 61. DLIDatabaseView Example Code IMS Java User’s Guide
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |
In our dealership example, there is only a single PCB defined in the dealership PSB. If there were other PCBs defined, they would be added to the DLIDatabaseView by: 1. Providing a separate array of DLISegmentInfo objects for the additional PCB. 2. Calling the method addDatabase within our Dealer constructor after the call to super, and passing the reference name of the PCB, the real name of the PCB, and the variable defining the array of DLISegmentInfo objects.
DLISegment Example Using the extracted database name and segment names from Figure 60 on page 100, you create a DLISegment dealer. The numbers in the following list (for example, 1) are referenced in Figure 62. Note the following: v You create an array of DLITypeInfo objects, one entry for each field used by the application. 1 v Each DLITypeInfo object defines the name, type, starting offset, length, and optionally the name of the field in the DBD. If you want to search on a field in a DLITypeInfo object, add the name of the field as specified in the DBD. You can have more fields than those named in the DBD. For example the field “DealerAddr” is a character field that starts at offset 35 for a length of 20 bytes and is not defined in the DBD. 2 To search on a field, the field name must be defined in the DBD file, and the field name as listed in the DBD must be provided to the DLITypeInfo object. v The segment name, DEALER, is passed in the Dealer constructor to the DLISegment constructor with the array of DLITypeInfo objects and the length of the entire array. 3 The easiest way to calculate that length is to add the starting offset of the last field in the array to its length and subtract 1. In this example: 55 + 7 -1 = 61. static DLITypeInfo[] dealerInfo = new DLITypeInfo("DealerNo", new DLITypeInfo("DealerName", new DLITypeInfo("DealerAddr", 2
{ 1 DLITypeInfo.CHAR 1, 4, "DLRNO"), DLITypeInfo.CHAR 5, 30, "DLRNAME"), DLITypeInfo.CHAR 35, 20),
new DLITypeInfo("DealerCity", DLITypeInfo.CHAR 35, 10, "CITY"), new DLITypeInfo("DealerZip", DLITypeInfo.CHAR 45, 10, "ZIP") new DLITypeInfo("DealerPhone", DLITypeInfo.CHAR 55, 7, "PHONE"), }; static DLISegment dealerSegment = new DLISegment("DealerSegment", "DEALER", dealerInfo, 61); 3 Figure 62. Example DLISegment Code
Appendix A. Manually Creating IMS Java Metadata Classes
103
104
IMS Java User’s Guide
Appendix B. High Performance Java | |
This appendix provides the compile and runtime options for High Performance Java. This method, although supported, is not recommended. In this chapter: v “Compile and Runtime Options” v “Installation Verification Process” on page 107
Compile and Runtime Options IMS does not support setting environmental variables before running an application; instead, you must set any environmental variables needed by an application at compile time. The following options must be set at compile time: -lerunopts=″ENVAR″ Allows environment variables to be defined in the executable for use at runtime. Set the following environment variables with this option: CLASSPATH An environment variable used during runtime to locate class files. CLASSPATH must be set to point to the imsjava library code, and the hpj runtime library code. Default installation locations are: /usr/lpp/ims/imsjava71/imsjava.jll and /usr/lpp/hpj/lib, respectively. -lerunopts="ENVAR(’CLASSPATH=/usr/lpp/hpj/lib:/usr/lpp/ims /imsjava71/imsjava.jll’, ’IBMHPJ_HOME=/usr/lpp/hpj’)"
IBMHPJ_HOME Identifies the root of the hpj files, and is used to locate hpj libraries at runtime. It is typically /usr/lpp/hpj. LIBPATH Identifies additional locations for runtime to search for library files. In particular, it can be used to find a UNIX link to the IMS Java native code library if the installation default is changed. At installation, this link is /usr/lpp/ims/imsjava71/libJavTDLI.dll, which points to the PDSE member DFSCLIB. You can create the UNIX link libJavTDLI.so to point to DFSCLIB in any location included in the LIBPATH. -include Use this option of the hpj command to include objects in your executable. Objects that need to be included are those that are dynamically loaded at runtime. For example, if you provide your database view as a string instead of creating an instance of the view in your application, you must include that string in your executable. This option is necessary any time you are writing JDBC applications. You must include all database views. An example of the -include option follows: -include=dealership.application.DealerDatabaseView
-exclude Use this option of the hpj command to exclude objects from being statically bound to your executable. The exclude statements in Figure 63 on page 106 illustrate how to dynamically access the IMS Java classes:
© Copyright IBM Corp. 2000, 2002
105
-exclude=com.ibm.ims.base.* -exclude=com.ibm.ims.application.* -exclude=com.ibm.ims.db.*
Figure 63. -exclude statement example
-main=classname Use this option to specify the class that contains the main startup method, which is used as the main entry point for the executable. -make Use this option to rebind only those objects that have changed. Although you can use the -make option when building a Java executable or DLL for the first time, you normally use this option when you are doing incremental rebind to refresh an existing Java executable or DLL. -target=IMS Use this required option to indicate that the program will be an IMS application. -o=executable Use this option to explicitly name the Java executable or DLL that you are building in the hfs file system or as a PDSE (partitioned dataset extended) member. -alias=name Use this option to specify an alias or hierarchical file system (HFS), such as the name for a Java executable or DLL that is being written to a PDSE member. The option -alias must be specified for all Java DLLs that reside in PDSE members. Your application containing the main has to be in a PDSE. To build an application as an executable in a PDSE member named IMSAUTO, follow these steps: 1. Make the root of the source files the current directory: cd /u/usrt001
2. Compile the Java source files: javac dealership/application/*.java javac dealership/database/*.java
3. Bind the class files into an executable member named IMSAUTO of the PDSE AUTO.DEALERSHIP: hpj -make dealership.application.IMSAuto \ -main=dealership.application.IMSAuto \ -o="//’AUTO.DEALERSHIP(IMSAUTO)’" \ -alias=IMSAUTO \ -target=IMS \ -lerunopts="ENVAR(’CLASSPATH=/usr/lpp/hpj/lib:/usr/lpp/ims /imsjava71/imsjava.jll ’, ’IBMHPJ_HOME=/usr/lpp/hpj ’)" \ -exclude=com.ibm.ims.db.* \ -exclude=com.ibm.ims.application.* \ -include=dealership.application.DealerDatabaseView \ -exclude=com.ibm.ims.base.*
Figure 64. Binding the class files
106
IMS Java User’s Guide
Installation Verification Process The following are example steps to verify an IMS Java install. 1. Go to the directory in which IMS Java is installed: cd usr/lpp/ims/imsjava71
2. Compile the IVP Java programs: javac samples/ivp/*.java
3. Create the executable load module and put it in the IVP PGMLIB data set (which should be pre-allocated): hpj samples.ivp.IVP -main=samples.ivp.IVP \ -o="//’IVPEXEXX.PGMLIB(DFSIVP32)’" -alias=DFSIVP32 \ -target=IMS \ -lerunopts="ENVAR(’CLASSPATH=/usr/lpp/hpj/lib:/usr/lpp/ims /imsjava71/imsjava.jll ’, ’IBMHPJ_HOME=/usr/lpp/hpj ’)"
4. Add the IVP PGMLIB data set to the STEPLIB in the JCL that starts the IMS MPP region. In the installation verification process, this data set must come before any other data set with the same name (DFSIVP32) in the STEPLIB concatenation. The first data set with that name in the STEPLIB is the one that will be executed. STEPLIB DD DSN=IVPEXEXX.PGMLIB,DISP=SHR
5. Include the data set for the IMS Java class libraries and hpj class libraries in the STEPLIB: DD DD DD
DSN=hlq.SDFSJLIB,DISP=SHR DSN=VAJAVA.V2R0M0.SHPJMOD,DISP=SHR DSN=VAJAVA.V2R0M0.SHPOMOD,DISP=SHR
The HLQ (High Level Qualifier) is the PDSE that you specified during the installation process for IMS Java. 6. Change the version number of the HPJ to reflect the correct version of HPJ installed. 7. Submit the JCL to start the IMS MPP region. 8. Go to the IMS terminal and invoke the formatted screen for the transaction: /format IVTCC
An input screen as shown in Figure 65 on page 108 will be displayed:
Appendix B. High Performance Java
107
************************************************** * IMS INSTALLATION VERIFICATION PROCEDURE * ************************************************** TRANSACTION TYPE : CONVERSATIONAL DATE : 04/03/00 PROCESS LAST FIRST
CODE
(*1) :
NAME
(*1) PROCESS CODE ADD DELETE UPDATE DISPLAY TADD END
:
NAME
:
EXTENSION
NUMBER
:
INTERNAL
ZIP CODE
:
SEGMENT# :
Figure 65. Example of a Blank IMS Installation Verification Procedure Screen
9. Enter the appropriate input. Figure 66 shows an example for the display query: Figure 67 on page 109 displays the output of the transaction: ************************************************** * IMS INSTALLATION VERIFICATION PROCEDURE * ************************************************** TRANSACTION TYPE : CONVERSATIONAL DATE : 04/19/00 PROCESS CODE LAST FIRST
(*1)
NAME NAME
:
DISPLAY
:
LAST1
:
EXTENSION
NUMBER
:
INTERNAL
ZIP CODE
:
(*1) PROCESS CODE ADD DELETE UPDATE DISPLAY TADD END
SEGMENT# : Figure 66. Example IMS Installation Procedure Screen with Transaction Input Information
108
IMS Java User’s Guide
************************************************** * IMS INSTALLATION VERIFICATION PROCEDURE * ************************************************** TRANSACTION TYPE : CONVERSATIONAL DATE : 04/19/00 PROCESS LAST FIRST
CODE
(*1) :
NAME NAME
DISPLAY
:
LAST1
:
FIRST1
EXTENSION
NUMBER
:
8-111-1111
INTERNAL
ZIP CODE
:
D01/R01
ENTRY WAS DISPLAYED
(*1) PROCESS CODE ADD DELETE UPDATE DISPLAY TADD END
SEGMENT# :
Figure 67. Example IMS Installation Verification Procedure Screen with Transaction Output Information
Appendix B. High Performance Java
109
110
IMS Java User’s Guide
Bibliography This bibliography includes all the publications cited in this book, including the publications in the IMS library. | | | | | | | | | | | | | | | | | | | |
IBM Developer Kit for OS/390, Java 2 Technology Edition: New IBM Technology featuring Persistent Reusable Java Virtual Machines, SC34-6034 IMS Primer, SG24-5352 OS/390: Unix Systems Services Command Reference, SC28-1892 OS/390: Unix System Services File System Interface Reference, SC28-1909 OS/390: Unix Systems Services User’s Guide, SC28-1891 CICS Transaction Server for OS/390: CICS System Definition Guide, SC33-1682 WebSphere Application Server V4.0.1 for z/OS and OS/390 : Assembling Java 2 Platform, Enterprise Edition (J2EE) Applications, SA22-7836 WebSphere Application Server V4.0.1 for z/OS and OS/390 : System Management User Interface, SA22-7838
IMS Version 7 Library SC26-9419
ADB
SC26-9420
AS
SC26-9421
ATM
SC26-9422
APDB
SC26-9423
APDG
SC26-9424
APCICS
SC26-9425
APTM
SC26-9427
CG
SC26-9426
CQS
IMS Version 7 Administration Guide: Database Manager IMS Version 7 Administration Guide: System IMS Version 7 Administration Guide: Transaction Manager IMS Version 7 Application Programming: Database Manager IMS Version 7 Application Programming: Design Guide IMS Version 7 Application Programming: EXEC DLI Commands for CICS and IMS IMS Version 7 Application Programming: Transaction Manager IMS Version 7 Customization Guide IMS Version 7 Common Queue Server and Base Primitive Environment Guide and Reference
© Copyright IBM Corp. 2000, 2002
SC26-9436
CR
SC26-9428
DBRC
LY37-3738
DGR
LY37-3739
FAST
SC27-0832
IJUG
GC26-9429
IIV
GC26-9430
ISDT
SC26-9432
MIG
GC26-9433
MC1
GC26-1120
MC2
SC26-9434
OTMA
SC26-9435
OG
GC26-9437
RPG
SC26-9438
SOP
SC26-9440
URDBTM
SC26-9441
URS
IMS Version 7 Command Reference IMS Version 7 DBRC Guide and Reference IMS Version 7 Diagnosis Guide and Reference IMS Version 7 Failure Analysis Structure Tables (FAST) for Dump Analysis IMS Version 7 IMS Java User’s Guide IMS Version 7 Installation Volume 1: Installation and Verification IMS Version 7 Installation Volume 2: System Definition and Tailoring IMS Version 7 Master Index and Glossary IMS Version 7 Messages and Codes, Volume 1 IMS Version 7 Messages and Codes, Volume 2 IMS Version 7 Open Transaction Manager Access Guide IMS Version 7 Operations Guide IMS Version 7 Release Planning Guide IMS Version 7 Sample Operating Procedures IMS Version 7 Utilities Reference: Database and Transaction Manager IMS Version 7 Utilities Reference: System
Supplementary Publications GC26-9431
LPS
SC26-9439
SOC
IMS Version 7 Licensed Program Specifications IMS Version 7 Summary of Operator CommandsSummary of Operator Commands
Publication Collections LK3T-3526 LBOF5294
CD
IMS Version 7 Licensed Product Kit: Online Library Hardcopy Licensed Bill of Forms (LBOF): and CD IMS Version 7 Hardcopy and Online Library
111
Publication Collections SBOF5297
SK2T-0730 SK2T-6700
112
Hardcopy Unlicensed Bill of Forms (SBOF): IMS Version 7 Unlicensed Hardcopy Library CD IBM Online Library: Transaction Processing and Data CD IBM Online Library OS/390
IMS Java User’s Guide
Index Special characters -exclude 105 -include 105
A abends 0118 93 0475 94 batch run failure 94 commit failure 93 description 93 ABENDU0118 93 ABENDU0475 94 adding Trace statements to applications aggregate keywords 35 AIB interface 3 AIBERRXT 93 applications batch 2 CICS environment 59 DB2 environment 59 JBP 2 JMP 2 message driven 2 message processing, building 46 non-message driven 2 processing 46 programming 42 that work with IMS 45 asterisk operator 38
B batch programs 45 batch run failure 94 BIGINT data type 32 BINARY data type 32 BIT data type 32 buffers main storage 46 byte data type 32
C CHAR data type 32 CICS configuring for IMS Java 13 CICS environment IMS Java application 59 installation verification 14 overview 2 programming model 59 restrictions 13 system requirements 13 class DLIDatabaseView 41 © Copyright IBM Corp. 2000, 2002
97
class (continued) DLIRecord 41 DLISegment 41 DLISegmentInfo 41 DLITypeInfo 41 java.sql.DatabaseMetaData 31 java.sql.Driver 31 java.sql.Statement 31 SSAQualificationStatement 41 CLASSPATH 16 COBOL copybook types 33 mapping to IMS 33 command input 46 commit 31 commit failure 93 configuration CICS environment 13 WebSphere for z/OS environment 9 Connection object executing 29 Connection.commit 31 Connection.rollback 31 Connection.setAutoCommit 31 control statements DLIModel utility 62, 66 example 85 format 68 including 73 syntax 74 typical sequence 67 when to use 67 controlling the amount of tracing 96 conventions naming 28 conversational transactions 52 copybook types 33
D data types conversion 32 mapped to COBOL 33 database metamodel XMI 65 database segment description 27 DATE data type 32 DB2 environment configuring 15 ENVAR settings 16 IMS Java applications 59 installation verification 17 overview 2 programming model 59 restrictions 15 setup 15 system requirements 15
113
DB2_HOME 16 DBD (Database Definition) example 25 DD statements 75 dealership sample overview 23 debugging 91 IMSTrace 96 default values assigning 99 DELETE statement 39 design process 1 determining problems in your applications IMSTrace 96 DFHJVMPR 13 DFSDLA00 93 DFSJVMAP 5 DFSJVMEV 5 DFSMODEL member 19 DFSTMS00 93 DL/I data accessing 43 DL/I PCB status codes 93 DL/I status codes mapping to exceptions 91 DLIConnection 41, 91 creating 42 DLIDatabaseView 41 example 101 mapping the DBD 100 DLIDriver loading 29 registering 29 DLIException 91 DLIModel Java Report database summary 64 example 25 fields 27 PCBs 26 DLIMODEL MVS Procedure preparing 19 DLIModel utility control statements 62, 66 description 61 inputs and outputs 62 limitations 63 logical relationship example 79 metadata classes creating 61 MVS procedure EXEC statement 21 script file 20 MVS USS prompt 21 output types 64 overview 61 procedure 74 PSB requirements 63 report 61 restrictions 64 running 74 running as MVS job 74
114
IMS Java User’s Guide
DLIModel utility (continued) running from USS 77 secondary index example 83 setup 19 MVS procedure 19 simple example 77 use 27 using 61, 77 DLIRecord 41 DLISegment 41 example 103 DLISegmentInfo 41 DLITypeInfo 41 DLITypeInfoList 55 doBegin() implementing 48 documenting an application’s flow of control DOUBLE data type 32 driver registering with DriverManager 29 DriverManager 30 DSNAME parameter 75 dump processing 94
E EAR (Enterprise Archive) 11 EJB (Enterprise Java Bean) deploying 9 overview 2 EJB (Enterprise Java Bean)deploying 11 Enterprise Java Bean (EJB) See EJB (Enterprise Java Bean) 2 ENVIRON 5 environments CICS configuring 13 installation verification 14 overview 2 restrictions 13 system requirements 13 DB2 configuring 15 installation verification 17 overview 2 restrictions 15 general restrictions 3 setup 3 system requirements 3 IMS configuration 4 installation verification 6 JMP 4 overview 1 restrictions 2, 4 setup 4 system requirements 4 WebSphere for z/OS installation verification 12 overview 2
96
environments (continued) WebSphere for z/OS (continued) restrictions 8 setup 8 system requirements 8 Environments WebSphere for z/OS EJB, deploying 11 exceptions description 91 mapping to DL/I status codes 91 EXEC statement parameters 75
F Field statement 67, 71 fields default values, assigning float data type 32 FROM clause 37
99
G genXMI parameter 65 getAIB 91 getFunction 91 getNextException 92 getStatusCode 91 GU message failure 93
H HFS (Hierarchic File System) 3 High Performance Java See HPJ (High Performance Java) HPJ (High Performance Java) compile options 105 installation verification 107 runtime options 105
I import statements 29 IMS application processing 45 applications in Java 45 call analyzer module 93 IMS databases (DBD) database definition 99 accessing 23 JDBC 24 mapping to Java classes 99 relational, compared to 28 IMS environment configuration 4 installation verification 6 overview 1 restrictions 2 IMS Java alias 28
107
IMS Java (continued) data type support 32 databases supported 1 dependent regions 1 messages supported 1 overview 1 prerequisite knowledge xv restrictions 3 system requirements 3 IMS Java hierarchic database interface overview 1, 23 SSAs 23 IMS JDBC Connector 9 IMS JDBC Resource Adapter configuring 9 deploying 10 IMSApplication subclassing 48 IMSException 91 IMSFieldMessage 57 subclassing 47 IMSJdbcCustomService.xml 10 IMSMessageQueue 92 IMSMessageQueue.getUniqueMessage 56 IMSTrace 96 include option 105 Include statement 73 index field secondary 73 initiating IMSTrace 96 input command 46 message switch 46 messages defining 47 transaction message 46 INSERT statement 38 WHERE clause 38 installation verification CICS environment 14 DB2 environment 17 IMS environment 6 WebSphere for z/OS environment 12 int data type 32 INTEGER data type 32 IVP (installation verificaiton program) See installation verification 14
J J2EE server configuring 9 EJB, deploying 11 IMS JDBC Resource Adapter, locating JVM properties 10 modifying properties 9 overview 2 java batch processing (JBPs) 45 Java classes mapping to IMS databases 99 Java data types 32
9
Index
115
java message processing (JMPs) 45 JAVA_HOME 16 java.math.BigDecimal 32 java.sql.Connection 30 java.sql.DatabaseMetaData 31 java.sql.Date 32 java.sql.Driver 31 java.sql.PreparedStatement 32 java.sql.ResultSet 32 java.sql.ResultSetMetaData 32 java.sql.Statement 31 java.sql.Time 32 java.sql.Timestamp 32 JAVAENV data set 16 JBP (Java Batch Processing) configuring 5 overview 2 JBPs 45 JDBC classes 27 Connection object, returning 29 data types 32 field names 27 IMS databases accessing 24 interfaces, limitations 30 overview 1, 23 prerequisite knowledge xv JMP (Java Message Processing) configuring 4 overview 2 JMPs 45 JVM master 4 worker 5 JVM regions, overview 1 JVMOPMAS 4 JVMOPWRK 5
K keywords aggregate 35 supported 35
L LIBPATH 16 local transactions 3 logical relationships DLIModel utility example 79 logical terminal (LTERM) 54 long data type 32 LTERM 54
M main storage buffers main() 48 master JVM 4
116
46
IMS Java User’s Guide
message processing application building 46 message processing applications message queue 46 message switch input 46 messages input defining 47 processing multiple 56 retrieving 56 message queue in Java 46 multi-segment 54 output, defining 47 reading and writing 46 repeating structures accessing 55 SPA 52 metadata class creating 24 metadata classes creating 61 creating manually 99 generated 64 multi-segment messages 54
46
N naming conventions SQL 35 nested structures accessing 55
O object DLIConnection 41 DLIConnection, creating 42 DriverManager 30 java.sql.Connection 30 SSA 41 ODBA (Open Database Access) options include 105 Options statement 66, 68 output messages defining 47
9
P P processing option 3 package database 30 PACKEDDECIMAL data type 32 PARM parameter 75 path call 38 PCB statement 67 prepared statement 40 PreparedStatement object 29, 36 prerequisite knowledge xv problem determination 91 PROC statement parameters 75
processing applications 46 processing dumps 94 program types 45 programming models CICS environment 59 DB2 environment 59 JBP 51 JMP 50 PRSUFFIX 14 PSB metadata class 61 XMI description 61 PSB (Program Specification Block) example 25 IMS Java metadata classes, relationship PSB statement 66, 70
Q queuing messages
46
R Rational Rose metamodel 66 reason codes 93 repeating structures accessing 55 report DLIModel utility 61 requirements, system 3 restrictions 3 CICS environment 13 DB2 environment 15 WebSphere for z/OS 8 ResultSet iterating 29 return codes 93
S sample message processing application 46 scratch pad area (SPA) 52 secondary index DLIModel utility example 83 secondary index field 73 SEGM statement 67, 70 segment instances querying 29 segment search arguments (SSAs) 41 segments default values, assigning 99 SELECT statement asterisk operator 38 description 35 setting up tracing 96 short data type 32 SMALLINT data type 32 SPA 52, 54
24
SPA message defining 53 SQL DELETE statement 39 FROM clause 37 INSERT statement 38 keywords 34, 35 naming conventions 35 prepared statement 40 referring to Java Report 64 SELECT statement 35 supported grammar 34 UPDATE statement 39 using a Statement object 36 SQL query example 28 SQLException 92 SQLquery naming conventions 28 SQLstate 92 SSA 41 SSAList 41 creating an 42 DL/I data, accessing 43 SSAQualificationStatement 41 SSAs 37, 41 starting IMSTrace 96 Statement object 36 retrieving 29 status codes 93 CR 93 mapping 91 STDENV DD statement 75 STDERR DD statement 76 STDOUT DD statement 75 Stored Procedures See DB2 environment 15 String data type boolean data type 32 structures nested accessing 55 sync point failure 93 processor 93 SYSOUT parameter 75 system requirements 3 CICS environment 13 DB2 environment 15 WebSphere for z/OS environment SYSTSIN DD statement 76
8
T TIME data type 32 TIMESTAMP data type 32 TINYINT data type 32 TMPREFIX 14 TMSUFFIX 16 tracing IMS Java library routines
96 Index
117
tracing (continued) IMSTrace 96 Trace statements, adding 97 transaction message input 46 transactions conversational 52 local 3 turning on IMSTrace 96 types data, mapped to COBOL 33 supported 32
U UPDATE statement 39 URL (universal resource locator) USS (Unix System Services) DLIModel utility, running 21
30
V VARCHAR data type
32
W WebSphere for z/OS DRA startup table 9 EJB, deploying 9, 11 IMS JDBC Resource Adapter 9 J2EE server 2 ODBA 9 WebSphere for z/OS environment accessing IMS 9 configuring 9 DRA startup table 9 installation verification 12 overview 2 restrictions 8 setup 8 system requirements 8 WHERE clause 38 worker JVM 5
X Xdfld statement 73 XMI creating 61 metamodel 65 XOPEN SQLstate 92
Z ZONEDECIMAL data type
118
IMS Java User’s Guide
32
Readers’ Comments — We’d Like to Hear from You IMS Version 7 IMS Java User’s Guide Publication No. SC27-0832-02 Overall, how satisfied are you with the information in this book?
Overall satisfaction
Very Satisfied h
Satisfied h
Neutral h
Dissatisfied h
Very Dissatisfied h
Neutral h h h h h h
Dissatisfied h h h h h h
Very Dissatisfied h h h h h h
How satisfied are you that the information in this book is:
Accurate Complete Easy to find Easy to understand Well organized Applicable to your tasks
Very Satisfied h h h h h h
Satisfied h h h h h h
Please tell us how we can improve this book:
Thank you for your responses. May we contact you?
h Yes
h No
When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any way it believes appropriate without incurring any obligation to you.
Name Company or Organization Phone No.
Address
SC27-0832-02
___________________________________________________________________________________________________
Readers’ Comments — We’d Like to Hear from You
Cut or Fold Along Line
_ _ _ _ _ _ _Fold _ _ _and _ _ _Tape _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Please _ _ _ _ _do _ _not _ _ staple _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Fold _ _ _and _ _ Tape ______ NO POSTAGE NECESSARY IF MAILED IN THE UNITED STATES
BUSINESS REPLY MAIL FIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK POSTAGE WILL BE PAID BY ADDRESSEE
IBM Corporation H150/090 555 Bailey Avenue San Jose, CA 95141-9989
_________________________________________________________________________________________ Fold and Tape Please do not staple Fold and Tape
SC27-0832-02
Cut or Fold Along Line
Program Number: 5655-B01
Printed in U.S.A.
SC27-0832-02
Spine information:
IMS Version 7
IMS Java User’s Guide
Related Documents
Ims Java Users Guide
October 2019 43
Java Guide
May 2020 15
Ims
November 2019 28
Ims
December 2019 46
Ims
June 2020 19