IMS Java Users Guide

IMS Version 7
IMS Java User’s Guide
SC27-0832-02
IMS Version 7
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 . . . . . . . . . . . . . . . . . . 1

| Design Process . . . . . . . . . . . . . . . . . . . . . . . . . 1
| IMS Environment Overview . . . . . . . . . . . . . . . . . . . . . 1
| WebSphere for z/OS Environment Overview . . . . . . . . . . . . . . 2
| CICS Environment Overview . . . . . . . . . . . . . . . . . . . . 2
| DB2 Environment Overview. . . . . . . . . . . . . . . . . . . . . 2
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 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 . . . . . . . . . . . . . . . 23

| Introduction to the Example Environment . . . . . . . . . . . . . . . 23
| JDBC Access Method . . . . . . . . . . . . . . . . . . . . . . 24
| Describing Your IMS Databases to IMS Java . . . . . . . . . . . . . 24
| Using JDBC to Access an IMS Database . . . . . . . . . . . . . . 27
| Classes and Field Names . . . . . . . . . . . . . . . . . . . 27
| PCB-Qualifying SQL Queries. . . . . . . . . . . . . . . . . . 28
| Writing an Application that Uses JDBC . . . . . . . . . . . . . . 29
| Supported Data Types in IMS Java . . . . . . . . . . . . . . . . 32
| General Mappings from COBOL Copybook Types to IMS Java and Java Data
| Types . . . . . . . . . . . . . . . . . . . . . . . . . . 33
| Supported SQL Grammar . . . . . . . . . . . . . . . . . . . . . 34
| SELECT . . . . . . . . . . . . . . . . . . . . . . . . . . 35
| Segment-Qualifying Fields. . . . . . . . . . . . . . . . . . . 35
| FROM . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
| WHERE . . . . . . . . . . . . . . . . . . . . . . . . . . 37
| INSERT . . . . . . . . . . . . . . . . . . . . . . . . . . 38
| DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . 39
| UPDATE . . . . . . . . . . . . . . . . . . . . . . . . . . 39
| JDBC Prepared Statements for SQL . . . . . . . . . . . . . . . . 40
| Recommendations for JDBC . . . . . . . . . . . . . . . . . . . 40
| IMS Java Hierarchic Database Interface . . . . . . . . . . . . . . . 41
| Application Programming Using DLIConnection . . . . . . . . . . . . 42
| Creating a DLIConnection Object . . . . . . . . . . . . . . . . . 42
| Building SSAs . . . . . . . . . . . . . . . . . . . . . . . . 42
| Accessing DL/I Data using SSAs . . . . . . . . . . . . . . . . 43
| Chapter 4. Writing a Java Application Program . . . . . . . . . . . . 45

IMS Applications . . . . . . . . . . . . . . . . . . . . . . . . 45
Overview of IMS Application Processing . . . . . . . . . . . . . . 45
Running Java Applications. . . . . . . . . . . . . . . . . . . 46
Message Queuing. . . . . . . . . . . . . . . . . . . . . . 46
Reading and Writing Messages to the Message Queue in Java . . . . . 46
Building an IMS Java Application by Example . . . . . . . . . . . . 46
Using IMS Java to Build a Message Processing Application . . . . . . 46
| Programming Models for IMS Java Applications . . . . . . . . . . . . 49
| JMP Programming Models . . . . . . . . . . . . . . . . . . 50
| JBP Programming Models . . . . . . . . . . . . . . . . . . . 51
Additional Programming Considerations . . . . . . . . . . . . . . . 52
Conversational Transactions . . . . . . . . . . . . . . . . . . 52
| Handling Multi-Segment Messages . . . . . . . . . . . . . . . 54
Coding and Accessing Messages with Repeating Structures . . . . . . 55
Flexible Reading of Multiple Input Messages . . . . . . . . . . . . 56
CICS Applications . . . . . . . . . . . . . . . . . . . . . . . . 59
DB2 Stored Procedures . . . . . . . . . . . . . . . . . . . . . 59
| Chapter 5. DLIModel Utility . . . . . . . . . . . . . . . . . . . . 61

| DLIModel Utility Overview . . . . . . . . . . . . . . . . . . . . . 61
| Requirements and Restrictions of the DLIModel Utility . . . . . . . . . . 63
| Requirements . . . . . . . . . . . . . . . . . . . . . . . . 63
| Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 63
| Output Types of the DLIModel Utility . . . . . . . . . . . . . . . . . 64
iv IMS Java User’s Guide

| IMS Java Metadata Classes . . . . . . . . . . . . . . . . . . . 64
| DLIModel Java Report . . . . . . . . . . . . . . . . . . . . . 64
| PSB Description . . . . . . . . . . . . . . . . . . . . . . 64
| PCB Description . . . . . . . . . . . . . . . . . . . . . . 64
| Segment Description . . . . . . . . . . . . . . . . . . . . . 64
| Field Description . . . . . . . . . . . . . . . . . . . . . . 64
| XMI Description of the Databases . . . . . . . . . . . . . . . . . 65
| DLIModel Trace . . . . . . . . . . . . . . . . . . . . . . . 66
| Control Statements for the DLIModel Utility . . . . . . . . . . . . . . 66
| Control Data Set Rules . . . . . . . . . . . . . . . . . . . . . 66
| Control Statement Rules . . . . . . . . . . . . . . . . . . . . 68
| Control Statement Syntax . . . . . . . . . . . . . . . . . . . . 68
| OPTIONS Statement. . . . . . . . . . . . . . . . . . . . . 68
| PSB Statement . . . . . . . . . . . . . . . . . . . . . . . 70
| PCB Statement . . . . . . . . . . . . . . . . . . . . . . . 70
| SEGM Statement . . . . . . . . . . . . . . . . . . . . . . 70
| FIELD Statement . . . . . . . . . . . . . . . . . . . . . . 71
| XDFLD Statement. . . . . . . . . . . . . . . . . . . . . . 73
| INCLUDE Statement . . . . . . . . . . . . . . . . . . . . . 73
| Comment Statement . . . . . . . . . . . . . . . . . . . . . 74
| Running the DLIModel Utility . . . . . . . . . . . . . . . . . . . . 74
| Running the DLIModel Utility as an MVS Job . . . . . . . . . . . . . 74
| PROC Statement Parameters . . . . . . . . . . . . . . . . . 75
| Step 1 EXEC Statement Parameters . . . . . . . . . . . . . . . 75
| Step 1 DD Statements . . . . . . . . . . . . . . . . . . . . 75
| Step 2 EXEC Statement Parameters . . . . . . . . . . . . . . . 76
| Step 2 DD Statements . . . . . . . . . . . . . . . . . . . . 76
| Running the DLIModel Utility From MVS Unix Systems Services . . . . . 77
| Examples of Using the DLIModel Utility . . . . . . . . . . . . . . . . 77
| Example 1. Simple Example . . . . . . . . . . . . . . . . . . . 77
| Example 2. Example With a Logical Relationship . . . . . . . . . . . 79
| Example 3. Example With a Secondary Index . . . . . . . . . . . . 83
| Example 4. Example with Multiple Control Statements . . . . . . . . . 85
Chapter 6. Problem Determination . . . . . . . . . . . . . . . . . 91

Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . 91
How Exceptions Map to DL/I Status Codes . . . . . . . . . . . . . 91
SQLExceptions . . . . . . . . . . . . . . . . . . . . . . . . 92
Sync Point Failure. . . . . . . . . . . . . . . . . . . . . . . . 93
| GU Message Failure . . . . . . . . . . . . . . . . . . . . . . . 93
Abends. . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
ABENDU0118 - Commit Failure . . . . . . . . . . . . . . . . . . 93
ABENDU0475 - Batch Run Failure . . . . . . . . . . . . . . . . 94
Processing Dumps . . . . . . . . . . . . . . . . . . . . . . 94
| DLIModel Messages . . . . . . . . . . . . . . . . . . . . . . . 94
IMSTrace . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Initiating IMSTracing . . . . . . . . . . . . . . . . . . . . . . 96
Setting up Tracing for the IMS Java Library Routines . . . . . . . . . . 96
Adding Trace Statements to Your Application . . . . . . . . . . . . . 97
| Appendix A. Manually Creating IMS Java Metadata Classes . . . . .

. 99 .
| Mapping an IMS Database in Java Classes . . . . . . . . . . . .
. 99 .
| IMS Database Definition (DBD) . . . . . . . . . . . . . . . .
. 99 .
| Adding Default Values for Fields of a Segment . . . . . . . . . .
. 99 .
| Mapping the PSB to DLIDatabaseView . . . . . . . . . . . . . . 100
| DLIDatabaseView Example . . . . . . . . . . . . . . . . . . . 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. Example of a Blank IMS Installation Verification Procedure Screen . . . . . . . . . . . . . 7
| 2. Example IMS Installation Procedure Screen with Transaction Input Information . . . . . . . . 7
| 3. Example IMS Installation Verification Procedure Screen with Transaction Output Information . . . 8
| 4. Example Database Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . 24
| 5. Example PSB Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
| 6. DBD Sample Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
| 7. The IMS Java Summary Report . . . . . . . . . . . . . . . . . . . . . . . . . 26
| 8. IMS DB Segments and Fields with Their Corresponding DB2 Tables and Columns . . . . . . 28
| 9. PCB-Qualifying SQL Query Example . . . . . . . . . . . . . . . . . . . . . . . 29
| 10. JDBC Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
| 11. Establish a Database Connection . . . . . . . . . . . . . . . . . . . . . . . . . 31
| 12. Example of SELECT Query Results . . . . . . . . . . . . . . . . . . . . . . . . 36
| 13. Sample Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
| 14. Sample Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
| 15. Sample INSERT Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
| 16. Sample DELETE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
| 17. Sample UPDATE Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . 39
| 18. Creating a DLIConnection Object . . . . . . . . . . . . . . . . . . . . . . . . . 42
| 19. Creating an SSAList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
20. Subclass IMSFieldMessage: Input Message Sample Code . . . . . . . . . . . . . . . 47
21. Subclass IMSFieldMessage: Output Message Sample Code . . . . . . . . . . . . . . . 48
22. Subclass IMSApplication Sample Code . . . . . . . . . . . . . . . . . . . . . . 49
| 23. Defining a SPA Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
24. Reading the SPA Message . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
25. Writing the SPA Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
| 26. Example Output Message . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
27. Defining the Primary Input Message . . . . . . . . . . . . . . . . . . . . . . . . 57
28. Creating the Input Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 58
29. Message Reading Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
| 30. The DLIModel Utility Inputs and Outputs . . . . . . . . . . . . . . . . . . . . . . 62
| 31. Sample DLIModel Utility PROC . . . . . . . . . . . . . . . . . . . . . . . . . 75
| 32. Physical DBD for Simple Example . . . . . . . . . . . . . . . . . . . . . . . . 78
| 33. PSB for Simple Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
| 34. Minimal MVS JCL stream. . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
| 35. Control Data Set for Simple Example . . . . . . . . . . . . . . . . . . . . . . . 78
| 36. DLIModel Java Report for Simple Example . . . . . . . . . . . . . . . . . . . . . 79
| 37. EMPDB2 Physical DBD for Logical Relationship Example . . . . . . . . . . . . . . . . 80
| 38. DEALDB2 Physical DBD for Logical Relationship Example . . . . . . . . . . . . . . . 80
| 39. Logical DBD for Logical Relationship Example . . . . . . . . . . . . . . . . . . . . 81
| 40. PSB with Field-Level Sensitivity for Logical Relationship Example . . . . . . . . . . . . . 81
| 41. Control Data Set for Logical Relationship Example . . . . . . . . . . . . . . . . . . 82
| 42. DLIModel Java Report for Logical Relationship Example . . . . . . . . . . . . . . . . 82
| 43. DBD for Secondary Index Example . . . . . . . . . . . . . . . . . . . . . . . . 83
| 44. Logical DBD for Secondary Index Example . . . . . . . . . . . . . . . . . . . . . 84
| 45. PSB for Secondary Index Example . . . . . . . . . . . . . . . . . . . . . . . . 84
| 46. MVS USS Command for Secondary Index Example . . . . . . . . . . . . . . . . . . 84
| 47. Control Data Set for Secondary Index Example . . . . . . . . . . . . . . . . . . . 84
| 48. DLIModel Java Report for Secondary Index Example . . . . . . . . . . . . . . . . . 85
| 49. Physical DBD for Multiple Control Statements Example. . . . . . . . . . . . . . . . . 86
| 50. PSB for Multiple Control Statements Example . . . . . . . . . . . . . . . . . . . . 86
| 51. MVS USS Command for Control Statements Example . . . . . . . . . . . . . . . . . 86
| 52. Top-Level Control Data Set for Multiple Control Statements Example. . . . . . . . . . . . 87
| 53. Second-Level Control Data Set for Multiple Control Statements Example . . . . . . . . . . 88
© Copyright IBM Corp. 2000, 2002 vii

| 54. DLIModel Java Report for Multiple Control Statements Example . . . . . . . . . . . . . 89
| 55. Database access methods of DLIConnection . . . . . . . . . . . . . . . . . . . . 92
56. IMSException Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
| 57. Setting a Trace within a Static Method . . . . . . . . . . . . . . . . . . . . . . . 97
58. Setting Up IMSTrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
| 59. Example Database and Segments . . . . . . . . . . . . . . . . . . . . . . . . 99
| 60. DBD Sample Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
| 61. DLIDatabaseView Example Code . . . . . . . . . . . . . . . . . . . . . . . . 102
| 62. Example DLISegment Code . . . . . . . . . . . . . . . . . . . . . . . . . . 103
63. -exclude statement example . . . . . . . . . . . . . . . . . . . . . . . . . . 106
64. Binding the class files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
65. Example of a Blank IMS Installation Verification Procedure Screen . . . . . . . . . . . . 108
66. Example IMS Installation Procedure Screen with Transaction Input Information . . . . . . . 108
67. Example IMS Installation Verification Procedure Screen with Transaction Output Information 109
viii IMS Java User’s Guide

Tables
| 1. Supported Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
| 2. ResultSet.getxxx Methods to Retrieve JDBC Types . . . . . . . . . . . . . . . . . . 33
| 3. Mapping from COBOL to IMS and Java . . . . . . . . . . . . . . . . . . . . . . 34
| 4. DLITypeInfo Constants and Java Types based on PICTURE clause . . . . . . . . . . . . 34
| 5. CopyBook Formats Mapped to IMS Java Types . . . . . . . . . . . . . . . . . . . 34
6. Status Code, Reason, and Return Code . . . . . . . . . . . . . . . . . . . . . . 93
| 7. Status Code, Reason, and Return Code . . . . . . . . . . . . . . . . . . . . . . 93
© Copyright IBM Corp. 2000, 2002 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 MVS
DB2 OS/390
CICS WebSphere
IBM z/OS
IMS
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 Conversational and non-conversational transactions
| v Multi-segment and single-segment messages
| v Message Formatting Services (MFS)
| v Alternate PCB program switching
| Regardless of what environment the IMS Java application runs in, it accesses the
| IMS databases the same way.
|
| 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 “IMS Setup” on page 4
| v “WebSphere for z/OS Setup” on page 8
| v “CICS Setup” on page 13
| v “DB2 Setup” on page 15
| v “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

| 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

| To run IMS Java applications in a JMP region, the region must be initialized with
| specific JVM options. Specify the following parameters:
| 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.
| 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.

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

| 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:
| 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.
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

IMS Setup
| An input screen as shown in Figure 1 is displayed.
|
| **************************************************
| * IMS INSTALLATION VERIFICATION PROCEDURE *
| **************************************************
|
|
| TRANSACTION TYPE : CONVERSATIONAL
| DATE : 04/03/00
|
| PROCESS CODE (*1) :
| (*1) PROCESS CODE
| LAST NAME : ADD
| DELETE
| FIRST NAME : UPDATE
| DISPLAY
| EXTENSION NUMBER : TADD
| END
| 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
|
| **************************************************
| **************************************************
|
|
| DATE : 04/19/00
|
| PROCESS CODE (*1) : DISPLAY
| (*1) PROCESS CODE
| LAST NAME : LAST1 ADD
| DELETE
| FIRST NAME : UPDATE
| DISPLAY
| EXTENSION NUMBER : TADD
| END
| INTERNAL ZIP CODE :
|
|
| SEGMENT# :
||
| Figure 2. Example IMS Installation Procedure Screen with Transaction Input Information
|
| displayed.
|

WebSphere for z/OS Setup
|
| **************************************************
| **************************************************
|
|
| DATE : 04/19/00
|
| PROCESS CODE (*1) : DISPLAY
| (*1) PROCESS CODE
| LAST NAME : LAST1 ADD
| DELETE
| FIRST NAME : FIRST1 UPDATE
| DISPLAY
| EXTENSION NUMBER : 8-111-1111 TADD
| END
| INTERNAL ZIP CODE : D01/R01
|
|
| Person found! 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

| begin a global transaction by calling javax.transaction.UserTransaction.begin in
| the EJB method before creating a Statement or PreparedStatement object.
| 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 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.
| To configure WebSphere for z/OS to access IMS databases:

| 1. Configure and deploy a DRA startup table.
| 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
| 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.
| 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:
| 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:

| 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:
| jar -xvf imsjava71.rar
| 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
| 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.
| 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
| 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.
| The following folders are displayed:
| J2EEServers
| Servers
| Systems
| J2EE Resources

| 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

| After you develop the EJB, deploy it on the 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.
| 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.
| J2EEServers
| Servers
| Systems
| J2EE Resources
| 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.

| 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:
| Administration tool.
| c. Navigate to the sysplex that will run the EJBs.
| J2EEServers
| Servers
| Systems
| J2EE Resources
| 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
| 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):
| Administration application.

| c. Navigate to the J2EEServers folder of the sysplex that will run the EJB.
| J2EEServers
| Servers
| Systems
| J2EE Resources
| 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.
| 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.
| 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.
| 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:

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 ==> cicsivp (or whatever program name you choose)
| Group ==> ivp (or whatever group name you choose)
| COncurrency ==> Threadsafe
| JVM ==> Yes
| JVMClass ==>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):

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 => cicsivp
| Group => 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.
| 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.
| 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

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:
| //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
| ENVAR Settings for the JAVAENV Data Set

| The JAVAENV data set must include the following ENVAR settings:
| 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:
| TMSUFFIX=/usr/lpp/ims/imsjava71/imsjava.jar
| The JAVAENV data set should have the following attributes:

| Organization . . . : PS
| Record format . . . : VB
| Record length . . . : 1028
| Block size . . . . : 6144
| For example:
| 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)
| The following is an example of JCL to define your stored procedure to

| SYSIBM.SYSROUTINES:
| //CREATJSP 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’)
| //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
| //PH061S01 EXEC PGM=IKJEFT01,DYNAMNBR=20
| //SYSTSIN DD *
| DSN SYSTEM(your_DB2_subsystem_name)
| RUN PROGRAM(DSNTIAD) PLAN(DSNTIA71) -
| PARM(’RC0’)
| //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:

DB2 Setup
| //CREATIVP JOB ,’YOUR NAME’,
| // MSGLEVEL=(1)
| //******************************************************************************
| //* Change xx in the PLAN(DSNTIAxx) to your DB2 version
| //* such as: 71 or 81
| //******************************************************************************
| //CREATJSP EXEC PGM=IKJEFT01,DYNAMNBR=20
| //SYSTSIN DD *
| DSN SYSTEM(DB2_Subsystem_Name)
| RUN PROGRAM(DSNTIAD) PLAN(DSNTIAxx) -
| PARM(’RC0’)
| //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’,
| // MSGLEVEL=(1)
| //*********************************************************************
| //* Change xx in the PLAN(DSNTEPxx) to your DB2 version
| //* such as: 71 or 81
| //*********************************************************************
| //BINDCLNT EXEC PGM=IKJEFT01,DYNAMNBR=20
| //DBRMLIB DD DISP=SHR,DSN=DB2HLQ.SDSNDBRM
| //SYSTSIN DD *
| DSN SYSTEM(DB2ID)
| BIND PACKAGE (DSNJDBC) MEMBER(DSNJDBC1) ISOLATION(UR) -
| ACTION(REPLACE) VALIDATE(BIND)
| BIND PACKAGE (DSNJDBC) MEMBER(DSNJDBC2) ISOLATION(CS) -
| BIND PACKAGE (DSNJDBC) MEMBER(DSNJDBC3) ISOLATION(RS) -
| BIND PACKAGE (DSNJDBC) MEMBER(DSNJDBC4) ISOLATION(RR) -
| 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

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 CLASSPATH=$JDBC_HOME/classes/db2jdbcclasses.zip
| export CLASSPATH=$CLASSPATH:$SQLJ_HOME/classes/db2sqljruntime.zip
| export CLASSPATH=$CLASSPATH:$SQLJ_HOME/classes/db2sqljclasses.zip
| export CLASSPATH=$CLASSPATH:/usr/lpp/ims/imsjava71/imsjava.jar
| export 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

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) (2)
QQ java 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):

| /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 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.
|

|
|
| 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.

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=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: 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: 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

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.
|

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:
| SELECT * FROM Model
| 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:
| SELECT * FROM Model WHERE ModelTypeCode = ’K1’
| 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

| 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:
|

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:
| import java.sql.*;
| 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:
| Class.forName("com.ibm.ims.db.DLIDriver");
| 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.
| connection = DriverManager.getConnection
| ("jdbc:dli:dealership.application.DealerDatabaseView");
| In this case, because the supplied string begins with jdbc:dli:, JDBC DriverManager
| locates the DLIDriver instance and requests that it create a connection.
|

JDBC Access Method
| package dealership.application;
| import com.ibm.ims.base.*;
| import com.ibm.ims.application.*;
| 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 {
| }
|
| 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

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:
|
|
| 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:
| 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.

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:
| ResultSet results = statement.executeQuery(queryString);
| 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 = ?).
| 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

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
| JDBC Types
PACKEDDECIMAL
ZONEDECIMAL
TIMESTAMP
SMALLINT
VARCHAR
INTEGER
DOUBLE
TINYINT
BINARY
BIGINT
FLOAT
CHAR
DATE
TIME
| ResultSet.getxxx
BIT
| Methods
| getByte 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 O O O O
| getBigDecimal O O O O O O O O O X X
| getBytes X
| getDate O O X O
| getTime O O X O
| getTimestamp O O O O X
|
| 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.
| 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.

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
3
| PIC 9 COMP-3 PACKEDDECIMAL java.math.BigDecimal
4
| PIC 9 DISPLAY ZONEDDECIMAL java.math.BigDecimal
|
| 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 DLITypeInfo Java Type
| Occupied Constant
| 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

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:

| SELECT CHILD.id
| FROM PCBName.CHILD
| WHERE ROOT.id=’10’
| 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.

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 {
| 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’

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
| 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.

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.
| SELECT *
| 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.
| 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:

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 {
| 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
|

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.
| – 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.
| 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.

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 SSA represents a Segment Search Argument. It provides methods to add
| command codes and qualification statements.
| 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

| 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
| 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
| 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.
| 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:

| // 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 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.

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.

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.
|
| /* 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
|
| /*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.

IMS Applications
| package dealership.ims;
|
| 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.

IMS Applications
| JMP Programming Models
| JMP programs get input messages from the IMS message queue, access IMS
| databases, commit transactions, and can send output messages.
| 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.
| 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(); //Close DB connection
| 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.
|
|
| repeat {
|
|
| ...
| ...
| 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

IMS Applications
| }
|
| return;
| }
| 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.
|
|
| repeat {
|
|
|
| ...
| ...
|
| IMSTransaction.commit(); //Commit & end transaction
| }
|
| return;
| }
| JBP Programming Models

| 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.
| 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.
|
|
| repeat {
|
| repeat {
| ...
| ...
| }
|
| IMSTransaction.commit(); //Periodic commits divide work
| }

IMS Applications
|
| return;
| }
| 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.
|
|
| repeat {
|
| repeat {
|
| ...
| ...
| IMSTransaction.rollback(); //Back out of DB
| //messages
|
| results=statement.executeQuery(...); //Perform more DB
| //processing (optional)
| ...
| MessageQueue.insertMessage(...); //Send more output
| //messages (optional)
| ...
| }
|
| IMSTransaction.commit(); //Periodic commits divide work
| }
|
| return;
| }
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

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
|

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

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:
| 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);
| }
| }
| The following code illustrates how the message queue is used to retrieve both
| messages:
| //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) {
| ...
| }
| Coding and Accessing Messages with Repeating Structures

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:

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

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.”

IMS Applications
public class ShowModelDetailsInput extends IMSFieldMessage {
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 {
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
}
}
public class CancelOrderInput extends IMSFieldMessage {
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
{
}
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.

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) { //Receives control
conn = DriverManager.getConnection(...); //Establish DB connection
repeat {
results = statement.executeQuery(...); //Perform DB processing
...
//send output to terminal
}
conn.close(); //Close DB connection

return;
}
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

IMS Applications
conn.close(); //Close DB connection

return;
}

|
| 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.
| v Create an XMI description 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 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
|

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.

| 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

| 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.

| 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
| 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.
| PCB Description
| 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.
| Segment Description
| 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.
| Field Description
| 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:

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

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 OPTIONS Statement \ PSB Statement \ Q
PCB Statement

DLIModel Utility Control Statements
|
|
Q \ Q
SEGM Statement \ \
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:
| 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.
| 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 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

| 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
| 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.
| The following diagram shows the syntax of the OPTIONS statement.
|
|
QQ OPTIONS \ PSBds= IMS.qual.dsname(member) Q
|
|
Q \ DBDds= IMS.qual.dsname(member) Q
Package= packagename
| GenJavaSource= NO GenXMI= NO GenTrace= NO

| Q Q
GenJavaSource= YES GenXMI= YES GenTrace= YES
| Q Q
| OutPath= path JavaSourcePath= path ReportPath= path

| 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
| DLIModel Java report. Overrides OutPath.
| XMIPath=path
| 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.

| 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 PSB statement is required because it defines which PSBs that the utility uses.
| Multiple PSB statements are allowed, unless the * wildcard form is specified.
| The following diagram shows the syntax of the PSB statement.
| QQ PSB PSBName= name QT

nameprefix* 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 PCB statement is optional. It specifies a Java alias for a PCB. All PCB
| statements for a PSB must follow the PSB statement.
| The following diagram shows the syntax of the PCB statement.
| QQ PCB PCBName= name JavaName= name QT

|
| 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
| The SEGM control statement is optional and used for physical and logical
| segments.
| 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

| 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
| 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.
| 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.

| 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
| Name= name Start= int Bytes= name
| Q Q
| JavaName= name JavaType= string TypeQualifier= string
| Q QT
| Default= string
|
| 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

| 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
| 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.
| 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 JavaName= name QT

|
| 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
| 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.
| 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 following diagram shows the syntax for the INCLUDE statement.
| QQ INCLUDE Dataset= IMS.qual.dsname(member) QT

path/filename
|
| 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:
|

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.

| 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
| COND
| See OS/390: Unix Systems Services User’s Guide and OS/390: Unix Systems
| 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:
| OCOPY INDD(HFSOUT) OUTDD(STDOUTL)
| OCOPY INDD(HFSERR) OUTDD(STDERRL)
| 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.

| The following JCL an example of a job that runs the DLIMODEL procedure:
| //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 *
| /*
| In this example, the IKJEFT01 SYSTSIN DD statement is provided with control

| cards to copy the temporary HFS outputs to MVS SYSOUT destinations.
| 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 com.ibm.ims.metagen.DLIModel path/ControlFile QT

|
| 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
|
| 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/
| 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.
|

DLIModel Utility Examples
| DBD NAME=DEALDB1,ACCESS=(HDAM,OSAM), X
| RMNAME=(DFSHDC40,1,5,200)
| DATASET DD1=DFSDLR
| SEGM NAME=DEALER,PARENT=0,BYTES=61
| FIELD NAME=(MAKE,SEQ,U),BYTES=10,START=1,TYPE=C
| DBDGEN
| FINISH
| END
|
| Figure 32. Physical DBD for Simple Example
|
|
| PCB1 PCB TYPE=DB,DBDNAME=DEALDB1,PROCOPT=A,KEYLEN=28
| 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 *
| /*
|
| 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)

| 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.
|
| ========================
| 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.
|

|
| DBD NAME=EMPDB2,ACCESS=(HDAM,OSAM), X
| 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
| SEGM NAME=EMPSAL,PARENT=EMPL,PTR=PAIRED, X
| 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
|
| Figure 37. EMPDB2 Physical DBD for Logical Relationship Example
|
|
| DBD NAME=DEALDB2,ACCESS=(HDAM,OSAM), X
| DATASET DD1=DFSDLR
| FIELD NAME=CITY,BYTES=10,START=35,TYPE=C
| FIELD NAME=(MODKEY,SEQ,U),BYTES=24,START=3, X
| TYPE=C
| FIELD NAME=MODTYPE,BYTES=2,START=1,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

| 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, X
| SOURCE=((EMPSAL,DATA,EMPDB2),(DEALER,DATA,DEALDB2))
| SEGM NAME=SALESINF,PARENT=DEALER, X
| SOURCE=((SALESINF,,DEALDB2))
| SEGM NAME=EMPLINFO,PARENT=EMPL, X
| SOURCE=((EMPLINFO,,EMPDB2))
| DBDGEN
| FINISH
| END
|
| 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
| 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.
|

| Options PSBds=IMSVS.TEST1.PSBSRC
| 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).
|
| ========================
| 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: 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)
|
| 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

| 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).
| LCHILD NAME=(SINDXA,SINDEX2),POINTER=INDX
| XDFLD NAME=XFLD2,SRCH=(LASTNME,FIRSTNME,ORDNBR), X
| DDATA=DATE
| 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.

|
| 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 SEARCH
| FIELD NAME=DATE,BYTES=10,START=57,TYPE=C DUP DATA
| LCHILD NAME=(ORDER,DEALDB2),INDEX=XFLD2
| DBDGEN
| FINISH
| END
|
| 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.
|

| 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, X
| PROCSEQ=SINDEX2
| SENSEG NAME=ORDER,PARENT=0
| SENSEG NAME=MODEL,PARENT=ORDER
| SENSEG NAME=DEALER,PARENT=MODEL
| END
|
| 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
| 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).
|

| ========================
| 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
|
| 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

| 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.
|
| DBDGEN
| FINISH
| END
|
| Figure 49. Physical DBD for Multiple Control Statements Example
|
|
| DLR_PCB1 PCB TYPE=DB,DBDNAME=DEALERDB,PROCOPT=GO,KEYLEN=42
| SENSEG NAME=ORDER,PARENT=MODEL
| SENSEG NAME=SALES,PARENT=MODEL
| SENSEG NAME=STOCK,PARENT=MODEL
| PSBGEN PSBNAME=DLR_PSB,MAXQ=200
| END
|
| 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.
|

| 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.
|

| SEGM DBDName=DEALERDB SegmentName=DEALER JavaName=DEALERXX
| FIELD Name=DLRNO Start=1 Bytes=4 JavaType=CHAR JavaName=DealerNumber
| FIELD Start=5 Bytes=30 JavaType=CHAR JavaName=DealerName
| FIELD Start=35 Bytes=50 JavaType=CHAR JavaName=DealerAddress
| FIELD Start=85 Bytes=10 JavaType=PACKEDDECIMAL TypeQualifier=S9(18) 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 SegmentName=ORDER JavaName=ORDERXX
| FIELD Name=ORDNBR Start=1 Bytes=6 JavaType=CHAR JavaName=OrderNumber
| FIELD Start=7 Bytes=30 JavaType=CHAR JavaName=Options
| FIELD Start=37 Bytes=5 JavaType=ZONEDDECIMAL TypeQualifier=99999 JavaName=Price
| FIELD Start=42 Bytes=8 JavaType=CHAR JavaName=OrderDate
| FIELD Name=LASTNME Start=50 Bytes=25 JavaType=CHAR JavaName=PurchaserLastName
| FIELD Name=FIRSTNME Start=75 Bytes=25 JavaType=CHAR JavaName=PurchaserFirstName
| FIELD Start=100 Bytes=8 JavaType=CHAR JavaName=SerialNo
| FIELD Start=120 Bytes=8 JavaType=CHAR JavaName=DeliverDate
|
| SEGM DBDName=DEALERDB SegmentName=SALES JavaName=SALESXX
| FIELD Name=SALDATE Start=1 Bytes=8 JavaType=CHAR JavaName=DateSold
| FIELD Name=LASTNME Start=9 Bytes=25 JavaType=CHAR JavaName=PurchaserLastName
| FIELD Name=FIRSTNME Start=34 Bytes=25 JavaType=CHAR JavaName=PurchasetFirstName
| FIELD Start=59 Bytes=25 JavaType=CHAR JavaName=PurchaserAddress
| FIELD Start=84 Bytes=10 JavaType=CHAR JavaName=SoldBy
| FIELD Name=STKVIN Start=94 Bytes=20 JavaType=CHAR JavaName=StockVINumber
|
| SEGM DBDName=DEALERDB SegmentName=STOCK JavaName=STOCKXX
| FIELD Name=STKVIN Start=1 Bytes=20 JavaType=CHAR JavaName=StockVINumber
| FIELD Start=21 Bytes=8 JavaType=CHAR JavaName=DateIn
| FIELD Start=29 Bytes=8 JavaType=CHAR JavaName=DateOut
| FIELD Name=COLOR Start=37 Bytes=10 JavaType=CHAR JavaName=Color
| FIELD Name=PRICE Start=47 Bytes=5 JavaType=ZONEDDECIMAL TypeQualifier=99999 JavaName=Price
| FIELD Name=LOT Start=53 Bytes=10 JavaType=CHAR 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.

| 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).
|
| ========================
| 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: 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: PurchaserFirstName Type=CHAR Start=75 Length=25 (Search Field)
| Field: Options Type=CHAR Start=7 Length=30
| 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: 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 ++ Primary Key Field ++
| Field: Color Type=CHAR Start=37 Length=10 (Search Field)
| 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 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 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.
|

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.

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 PCB System Category Description
Return/ Status Service
Reason Code Call
Code
0108/ SY IMS Java 5 Internal error during sync point processing for
056C sync 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 PCB System Category Description
| Return/ Status Service
| Reason Code Call
| Code
| 0104/ CR IMS Java 4 Application error during GU message
| 0300 GU processing for an IMS Java application.
| Message
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) | DHM0002 through DHM0199 text (class/method)
| (DHM0001E) | (DHM0xxxE)
| Explanation: This message describes a probable error | Explanation: Messages in this range describe
| in the DLIModel utility during the import of a PSB or | problems in the input data that prevent the utility from
| DBD. | 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, | (class/method)
| in DLIModel at which the error was detected | -describes the location; class or method name,
| in DLIModel at which the error was detected
| (DHM00001E)
| -the message reference number | (DHM0xxxE)
| -the message reference number
| Programmer Response: Call IBM for service. Have
| these things available: | xxx the last three digits of the message
| v the content of this message | number, in the range: 2 through 199
| v the input PSBs and all related DBDs | Programmer Response: Typically, this error is the
| v control statement data set or file | result of incorrect or inconsistent PSB or DBD source
| data. It is strongly recommended that PSBs and DBDs
| v the JCL or USS command that you used to execute
| are compiled, an ACBGEN is performed, and all errors
| the utility
| are corrected before running the DLIModel utility. If
| Problem Determination: You may be asked to rerun | these tasks are not done, there is no guarantee that the
| DLIModel with the option parameter, Trace=yes set in | DLIModel utility will detect all potential errors in the PSB
| order to aid in the problem determination.

DLIModel Messages
| or DBD source, so the resulting output might be | Programmer Response:
| incomplete or incorrect.
| Informational messages:
| If the PSBs and the DBDs have been validated (through | Confirm that the action that was performed by
| PSBGEN, DBDGEN, and ACBGEN) but the problem | the utility is acceptable.
| persists, call IBM for service. Have these things
| available:
| Warning messages:
| These messages describe an error that could
| v the content of this message | be corrected or ignored by the utility, allowing it
| v the input PSBs and DBDs | to continue,. Frequently this is done by ignoring
| v the control statement data set or file | part of one or more control statements.
| v the JCL or USS command that you used to execute | Confirm that the action that was performed by
| the utility | the utility is acceptable by reviewing the
| message and the generated output. Correct
| Problem Determination: You may be asked to rerun
| and rerun the utility if necessary.
| DLIModel with the option parameter, Trace=yes set in
| order to aid in the problem determination. | Error messages:
| These messages describe an error that caused
|
| the utility to terminate. Correct the error and
| DHM0200 through DHM0299 text (DHM02xxW)
| rerun the utility. In some cases, one of these
| Explanation: These messages describe warnings of | messages is followed by related messages that
| problems with the input data that did not prevent the | describe a system error, or an error or a
| DLIModel utility from continuing. In most cases part of | warning regarding input data.
| the input data is ignored in order to circumvent the
|
| problem, and this might result in incomplete output.
| DHM0800W through DHM0899W text (DHM008xxE)
| Explanation: These messages describe errors that
| (DHM02xxW) | occur during the export of the IMS Java metadata
| -the message reference number | classes and the Java report.
| xx the last two digits of the message | text -describes the problem
| number, in the range: 0 through 99
| (DHM08xxE)
| Programmer Response: The utility output (for | -the message reference number
| example the IMS Java metadata classes) should be
| xx the last two digits of the message
| carefully reviewed before use. In some cases the output
| number, in the range: 0 through 99
| will be usable after one of these warnings -- for
| example, a PSB may contain a PCB that references an | Programmer Response: Message DHM0800E
| MSDB type database, which cannot be handled by the | describes problems that are probable system errors.
| utility. The generated IMS Java classes report of the | Call IBM for service. Have the following things available:
| XMI file will omit the MSDB database, that would | the content of this message, the input PSB and all
| typically be acceptable for an IMS Java application that | related DBDs, control statement data set or file, and the
| used the metadata classes. | JCL or USS command that was used to execute the
| utility
|
| DHM0500 through DHM0599 text (DHM05xxy) | Other messages in this range are often caused by
| incorrect or inconsistent PSB or DBD source data. It is
| Explanation: These messages describe standard
| strongly recommended that PSBs and DBDs be
| actions taken, warnings, and errors that occur during
| compiled, an ACBGEN performed, and all errors
| the processing of the DLIModel control statement file.
| corrected before running the DLIModel utility. If these
| text -describes the problem | tasks are not done, there is no guarantee that the
| DLIModel utility will detect all potential errors in the PSB
| (DHM05xxy) | or DBD source, and the export of IMS Java entities may
| -the message reference number | fail, resulting in one of these messages.
| xx the last two digits of the message | If the PSBs and the DBDs have been validated (through
| number, in the range: 0 through 99 | PSBGEN, DBDGEN, and ACBGEN) but the problem
| y one of these severities: | persists, call IBM for service. Have these things
| available:
| I informational
| v the content of this message
| W warning | v the input PSBs and DBDs
| E error | v the control statement data set or file

DLIModel Messages
| v the JCL or USS command that you used to execute | DLIModel with the option parameter, Trace=yes set in
| the utility | 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):
| 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);
| These steps are best implemented within a static method of your main class, as
| shown in Figure 57 on page 97:
|

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 int applicationTraceLevel = IMSTrace.TRACE_CTOR3;
2. Set up IMSTrace to trace methods, parameters, and return values as necessary,
as shown in Figure 58:

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)

IMSTrace
public void doBegin() throws IMSException {
if (IMSAuto.applicationTraceLevel >= IMSTrace.TRACE_METHOD1)
IMSTrace.currentTrace().logEntry("IMSAuto.doBegin");
try {
//Add code here . . .
}
finally {
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";
}
finally {
IMSTrace.currentTrace().logExit("IMSAuto.method1");
}
return result;
}

|
| 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:

| 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.
|
| SEGM NAME=DEALER,PARENT=0,BYTES=94,
| DBDGEN
| FINISH
| END
|
| Figure 60. DBD Sample Definition
|

| 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

|
| 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);
| 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);
| 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
| 102 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 = { 1
| new DLITypeInfo("DealerNo", DLITypeInfo.CHAR 1, 4, "DLRNO"),
| new DLITypeInfo("DealerName", DLITypeInfo.CHAR 5, 30, "DLRNAME"),
| new DLITypeInfo("DealerAddr", DLITypeInfo.CHAR 35, 20),
| 2
|
| 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

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:

-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 \
/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

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 \
/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 DSN=hlq.SDFSJLIB,DISP=SHR
DD DSN=VAJAVA.V2R0M0.SHPJMOD,DISP=SHR
DD 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 CODE (*1) :

(*1) PROCESS CODE
LAST NAME : ADD
DELETE
FIRST NAME : UPDATE
DISPLAY
EXTENSION NUMBER : TADD
END
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:
**************************************************
**************************************************

DATE : 04/19/00
PROCESS CODE (*1) : DISPLAY

(*1) PROCESS CODE
LAST NAME : LAST1 ADD
DELETE
FIRST NAME : UPDATE
DISPLAY
EXTENSION NUMBER : TADD
END
INTERNAL ZIP CODE :
SEGMENT# :
Figure 66. Example IMS Installation Procedure Screen with Transaction Input Information

**************************************************
**************************************************

DATE : 04/19/00
PROCESS CODE (*1) : DISPLAY

(*1) PROCESS CODE
LAST NAME : LAST1 ADD
DELETE
FIRST NAME : FIRST1 UPDATE
DISPLAY
EXTENSION NUMBER : 8-111-1111 TADD
END
INTERNAL ZIP CODE : D01/R01
ENTRY WAS DISPLAYED SEGMENT# :
Figure 67. Example IMS Installation Verification Procedure Screen with Transaction Output
Information
Appendix B. High Performance Java 109

Bibliography
This bibliography includes all the publications cited SC26-9436 CR IMS Version 7 Command
in this book, including the publications in the IMS Reference
library. SC26-9428 DBRC IMS Version 7 DBRC Guide
| IBM Developer Kit for OS/390, Java 2 and Reference
| Technology Edition: New IBM Technology LY37-3738 DGR IMS Version 7 Diagnosis
| featuring Persistent Reusable Java Virtual Guide and Reference
| Machines, SC34-6034 LY37-3739 FAST IMS Version 7 Failure
Analysis Structure Tables
| IMS Primer, SG24-5352 (FAST) for Dump Analysis
| OS/390: Unix Systems Services Command SC27-0832 IJUG IMS Version 7 IMS Java
| Reference, SC28-1892 User’s Guide
| OS/390: Unix System Services File System GC26-9429 IIV IMS Version 7 Installation
Volume 1: Installation and
| Interface Reference, SC28-1909
Verification
| OS/390: Unix Systems Services User’s Guide, GC26-9430 ISDT IMS Version 7 Installation
| SC28-1891 Volume 2: System Definition
| CICS Transaction Server for OS/390: CICS and Tailoring
| System Definition Guide, SC33-1682 SC26-9432 MIG IMS Version 7 Master Index
and Glossary
| WebSphere Application Server V4.0.1 for z/OS
GC26-9433 MC1 IMS Version 7 Messages and
| and OS/390 : Assembling Java 2 Platform,
Codes, Volume 1
| Enterprise Edition (J2EE) Applications,
GC26-1120 MC2 IMS Version 7 Messages and
| SA22-7836 Codes, Volume 2
| WebSphere Application Server V4.0.1 for z/OS SC26-9434 OTMA IMS Version 7 Open
| and OS/390 : System Management User Transaction Manager Access
| Interface, SA22-7838 Guide
SC26-9435 OG IMS Version 7 Operations
Guide
IMS Version 7 Library GC26-9437 RPG IMS Version 7 Release
Planning Guide
SC26-9438 SOP IMS Version 7 Sample
SC26-9419 ADB IMS Version 7 Administration Operating Procedures
Guide: Database Manager
SC26-9440 URDBTM IMS Version 7 Utilities
SC26-9420 AS IMS Version 7 Administration Reference: Database and
Guide: System Transaction Manager
SC26-9421 ATM IMS Version 7 Administration SC26-9441 URS IMS Version 7 Utilities
Guide: Transaction Manager Reference: System
SC26-9422 APDB IMS Version 7 Application
Programming: Database
Manager Supplementary Publications
SC26-9423 APDG IMS Version 7 Application
Programming: Design Guide GC26-9431 LPS IMS Version 7 Licensed
Program Specifications
SC26-9424 APCICS IMS Version 7 Application
Programming: EXEC DLI SC26-9439 SOC IMS Version 7 Summary of
Commands for CICS and Operator CommandsSummary
IMS of Operator Commands
SC26-9425 APTM IMS Version 7 Application
Programming: Transaction Publication Collections
Manager
SC26-9427 CG IMS Version 7 Customization LK3T-3526 CD IMS Version 7 Licensed
Guide Product Kit: Online Library
SC26-9426 CQS IMS Version 7 Common LBOF5294 Hardcopy Licensed Bill of Forms (LBOF):
Queue Server and Base and CD IMS Version 7 Hardcopy and
Primitive Environment Guide Online Library
and Reference

Publication Collections
SBOF5297 Hardcopy Unlicensed Bill of Forms

(SBOF): IMS Version 7
Unlicensed Hardcopy Library
SK2T-0730 CD IBM Online Library: Transaction
Processing and Data
SK2T-6700 CD IBM Online Library OS/390

Index
Special characters class (continued)
DLIRecord 41
-exclude 105
DLISegment 41
-include 105
DLISegmentInfo 41
DLITypeInfo 41
java.sql.DatabaseMetaData 31
A java.sql.Driver 31
abends java.sql.Statement 31
0118 93 SSAQualificationStatement 41
0475 94 CLASSPATH 16
batch run failure 94 COBOL
commit failure 93 copybook types 33
description 93 mapping to IMS 33
ABENDU0118 93 command input 46
ABENDU0475 94 commit 31
adding Trace statements to applications 97 commit failure 93
aggregate keywords 35 configuration
AIB interface 3 CICS environment 13
AIBERRXT 93 WebSphere for z/OS environment 9
applications Connection object
batch 2 executing 29
CICS environment 59 Connection.commit 31
DB2 environment 59 Connection.rollback 31
JBP 2 Connection.setAutoCommit 31
JMP 2 control statements
message driven 2 DLIModel utility 62, 66
message processing, building 46 example 85
non-message driven 2 format 68
processing 46 including 73
programming 42 syntax 74
that work with IMS 45 typical sequence 67
asterisk operator 38 when to use 67
controlling the amount of tracing 96
conventions
B naming 28
batch programs 45 conversational transactions 52
batch run failure 94 copybook types 33
BIGINT data type 32
BINARY data type 32
BIT data type 32 D
buffers data types
main storage 46 conversion 32
byte data type 32 mapped to COBOL 33
database metamodel
XMI 65
C database segment
CHAR data type 32 description 27
CICS DATE data type 32
configuring for IMS Java 13 DB2 environment
CICS environment configuring 15
IMS Java application 59 ENVAR settings 16
installation verification 14 IMS Java applications 59
overview 2 installation verification 17
programming model 59 overview 2
restrictions 13 programming model 59
system requirements 13 restrictions 15
class setup 15
DLIDatabaseView 41 system requirements 15

DB2_HOME 16 DLIModel utility (continued)
DBD (Database Definition) running from USS 77
example 25 secondary index example 83
DD statements 75 setup 19
dealership sample MVS procedure 19
overview 23 simple example 77
debugging 91 use 27
IMSTrace 96 using 61, 77
default values DLIRecord 41
assigning 99 DLISegment 41
DELETE statement 39 example 103
design process 1 DLISegmentInfo 41
determining problems in your applications DLITypeInfo 41
IMSTrace 96 DLITypeInfoList 55
DFHJVMPR 13 doBegin()
DFSDLA00 93 implementing 48
DFSJVMAP 5 documenting an application’s flow of control 96
DFSJVMEV 5 DOUBLE data type 32
DFSMODEL member 19 driver
DFSTMS00 93 registering with DriverManager 29
DL/I data DriverManager 30
accessing 43 DSNAME parameter 75
DL/I PCB status codes 93 dump processing 94
DL/I status codes
mapping to exceptions 91
DLIConnection 41, 91 E
creating 42 EAR (Enterprise Archive) 11
DLIDatabaseView 41 EJB (Enterprise Java Bean)
example 101 deploying 9
mapping the DBD 100 overview 2
DLIDriver EJB (Enterprise Java Bean)deploying 11
loading 29 Enterprise Java Bean (EJB)
registering 29 See EJB (Enterprise Java Bean) 2
DLIException 91 ENVIRON 5
DLIModel Java Report environments
database summary 64 CICS
example 25 configuring 13
fields 27 installation verification 14
PCBs 26 overview 2
DLIMODEL MVS Procedure restrictions 13
preparing 19 system requirements 13
DLIModel utility DB2
control statements 62, 66 configuring 15
description 61 installation verification 17
inputs and outputs 62 overview 2
limitations 63 restrictions 15
logical relationship example 79 general
metadata classes restrictions 3
creating 61 setup 3
MVS procedure system requirements 3
EXEC statement 21 IMS
script file 20 configuration 4
MVS USS prompt 21 installation verification 6
output types 64 JMP 4
overview 61 overview 1
procedure 74 restrictions 2, 4
PSB requirements 63 setup 4
report 61 system requirements 4
restrictions 64 WebSphere for z/OS
running 74 installation verification 12
running as MVS job 74 overview 2

environments (continued) IMS Java (continued)
WebSphere for z/OS (continued) data type support 32
restrictions 8 databases supported 1
setup 8 dependent regions 1
system requirements 8 messages supported 1
Environments overview 1
WebSphere for z/OS prerequisite knowledge xv
EJB, deploying 11 restrictions 3
exceptions system requirements 3
description 91 IMS Java hierarchic database interface
mapping to DL/I status codes 91 overview 1, 23
EXEC statement parameters 75 SSAs 23
IMS JDBC Connector 9
IMS JDBC Resource Adapter
F configuring 9
Field statement 67, 71 deploying 10
fields IMSApplication
default values, assigning 99 subclassing 48
float data type 32 IMSException 91
FROM clause 37 IMSFieldMessage 57
subclassing 47
IMSJdbcCustomService.xml 10
G IMSMessageQueue 92
genXMI parameter 65 IMSMessageQueue.getUniqueMessage 56
getAIB 91 IMSTrace 96
getFunction 91 include option 105
getNextException 92 Include statement 73
getStatusCode 91 index field
GU message failure 93 secondary 73
initiating IMSTrace 96
input
H command 46
message switch 46
HFS (Hierarchic File System) 3
messages
High Performance Java
defining 47
See HPJ (High Performance Java) 107
transaction message 46
HPJ (High Performance Java)
INSERT statement 38
compile options 105
WHERE clause 38
installation verification 107
installation verification
runtime options 105
CICS environment 14
DB2 environment 17
IMS environment 6
I WebSphere for z/OS environment 12
import statements 29 int data type 32
IMS INTEGER data type 32
application processing 45 IVP (installation verificaiton program)
applications in Java 45 See installation verification 14
call analyzer module 93
IMS databases
(DBD) database definition 99
accessing 23
J
J2EE server
JDBC 24
configuring 9
mapping to Java classes 99
EJB, deploying 11
relational, compared to 28
IMS JDBC Resource Adapter, locating 9
IMS environment
JVM properties 10
configuration 4
modifying properties 9
overview 2
overview 1
java batch processing (JBPs) 45
restrictions 2
Java classes
IMS Java
mapping to IMS databases 99
alias 28
Java data types 32
Index 115
java message processing (JMPs) 45 message processing application
JAVA_HOME 16 building 46
java.math.BigDecimal 32 message processing applications 46
java.sql.Connection 30 message queue 46
java.sql.DatabaseMetaData 31 message switch input 46
java.sql.Date 32 messages
java.sql.Driver 31 input
java.sql.PreparedStatement 32 defining 47
java.sql.ResultSet 32 processing multiple 56
java.sql.ResultSetMetaData 32 retrieving 56
java.sql.Statement 31 message queue in Java 46
java.sql.Time 32 multi-segment 54
java.sql.Timestamp 32 output, defining 47
JAVAENV data set 16 reading and writing 46
JBP (Java Batch Processing) repeating structures
configuring 5 accessing 55
overview 2 SPA 52
JBPs 45 metadata class
JDBC creating 24
classes 27 metadata classes
Connection object, returning 29 creating 61
data types 32 creating manually 99
field names 27 generated 64
IMS databases multi-segment messages 54
accessing 24
interfaces, limitations 30
overview 1, 23 N
prerequisite knowledge xv naming conventions
JMP (Java Message Processing) SQL 35
configuring 4 nested structures
overview 2 accessing 55
JMPs 45
JVM
master 4 O
worker 5 object
JVM regions, overview 1 DLIConnection 41
JVMOPMAS 4 DLIConnection, creating 42
JVMOPWRK 5 DriverManager 30
java.sql.Connection 30
SSA 41
K ODBA (Open Database Access) 9
keywords options
aggregate 35 include 105
supported 35 Options statement 66, 68
output messages
defining 47
L
LIBPATH 16
local transactions 3 P
logical relationships P processing option 3
DLIModel utility example 79 package
logical terminal (LTERM) 54 database 30
long data type 32 PACKEDDECIMAL data type 32
LTERM 54 PARM parameter 75
path call 38
PCB statement 67
M prepared statement 40
main storage buffers 46 PreparedStatement object 29, 36
main() 48 prerequisite knowledge xv
master JVM 4 problem determination 91
PROC statement parameters 75

processing applications 46 SPA message
processing dumps 94 defining 53
program types 45 SQL
programming models DELETE statement 39
CICS environment 59 FROM clause 37
DB2 environment 59 INSERT statement 38
JBP 51 keywords 34, 35
JMP 50 naming conventions 35
PRSUFFIX 14 prepared statement 40
PSB referring to Java Report 64
metadata class 61 SELECT statement 35
XMI description 61 supported grammar 34
PSB (Program Specification Block) UPDATE statement 39
example 25 using a Statement object 36
IMS Java metadata classes, relationship 24 SQL query
PSB statement 66, 70 example 28
SQLException 92
SQLquery
Q naming conventions 28
queuing messages 46 SQLstate 92
SSA 41
SSAList 41
R creating an 42
Rational Rose DL/I data, accessing 43
metamodel 66 SSAQualificationStatement 41
reason codes 93 SSAs 37, 41
repeating structures starting IMSTrace 96
accessing 55 Statement object 36
report retrieving 29
DLIModel utility 61 status codes 93
requirements, system 3 CR 93
restrictions 3 mapping 91
CICS environment 13 STDENV DD statement 75
DB2 environment 15 STDERR DD statement 76
WebSphere for z/OS 8 STDOUT DD statement 75
ResultSet Stored Procedures
iterating 29 See DB2 environment 15
return codes 93 String data type
boolean data type 32
structures
S nested
accessing 55
sample
sync point
message processing application 46
failure 93
scratch pad area (SPA) 52
processor 93
secondary index
SYSOUT parameter 75
DLIModel utility example 83
system requirements 3
secondary index field 73
CICS environment 13
SEGM statement 67, 70
DB2 environment 15
segment instances
WebSphere for z/OS environment 8
querying 29
SYSTSIN DD statement 76
segment search arguments (SSAs) 41
segments
default values, assigning 99
SELECT statement
T
asterisk operator 38 TIME data type 32
description 35 TIMESTAMP data type 32
setting up tracing 96 TINYINT data type 32
short data type 32 TMPREFIX 14
SMALLINT data type 32 TMSUFFIX 16
SPA 52, 54 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) 30
USS (Unix System Services)
DLIModel utility, running 21
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
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 32

Readers’ Comments — We’d Like to Hear from You
IMS Version 7
Publication No. SC27-0832-02
Overall, how satisfied are you with the information in this book?
Very Satisfied Satisfied Neutral Dissatisfied Very Dissatisfied

Overall satisfaction h h h h h
How satisfied are you that the information in this book is:
Very Satisfied Satisfied Neutral Dissatisfied Very Dissatisfied

Accurate h h h h h
Complete h h h h h
Easy to find h h h h h
Easy to understand h h h h h
Well organized h h h h h
Applicable to your tasks 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 Address
Company or Organization
Phone No.
___________________________________________________________________________________________________
Readers’ Comments — We’d Like to Hear from You Cut or Fold
SC27-0832-02 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
Cut or Fold
SC27-0832-02 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 Users Guide

Caricato da

Informazioni sul documento

Descrizione originale:

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

IMS Java Users Guide

Caricato da

Copyright:

Formati disponibili

IMS Version 7

IMS Java User’s Guide

IMS Java User’s Guide

Third Edition (August 2002) (Softcopy Only)

Summary of Changes . . . . . . . . . . . . . . . . . . . . . xvii

| Chapter 1. Overview of IMS Java . . . . . . . . . . . . . . . . . . 1

Chapter 2. Setting Up Your Environment for IMS Java. . . . . . . . . . 3

© Copyright IBM Corp. 2000, 2002 iii

| Chapter 3. Accessing an IMS Database . . . . . . . . . . . . . . . 23

| Chapter 4. Writing a Java Application Program . . . . . . . . . . . . 45

| Chapter 5. DLIModel Utility . . . . . . . . . . . . . . . . . . . . 61

iv IMS Java User’s Guide

Chapter 6. Problem Determination . . . . . . . . . . . . . . . . . 91

| Appendix A. Manually Creating IMS Java Metadata Classes . . . . .

Appendix B. High Performance Java . . . . . . . . . . . . . . . 105

vi IMS Java User’s Guide

© Copyright IBM Corp. 2000, 2002 vii

viii IMS Java User’s Guide

© Copyright IBM Corp. 2000, 2002 ix

This information could include technical inaccuracies or typographical errors.

© Copyright IBM Corp. 2000, 2002 xi

Such information may be available, subject to appropriate terms and conditions,

Any performance data contained herein was determined in a controlled

This information contains sample application programs in source language, which

xii IMS Java User’s Guide

© Copyright IBM Corp. 2000, 2002 xv

| This book has undergone major organizational changes in addition to technical

| Other changes include changes to these following books:

© Copyright IBM Corp. 2000, 2002 xvii

xviii IMS Java User’s Guide

| IMS Java application programs can be message-driven or non-message-driven and

© Copyright IBM Corp. 2000, 2002 1

2 IMS Java User’s Guide

| Related Reading: For systems requirements for specific environments, see:

| Related Reading: For restrictions on specific environments, see:

© Copyright IBM Corp. 2000, 2002 3

| IMS System Requirements

| JBP applications must be non-message-driven applications.

| JMP and JBP applications cannot access DB2 databases.

| “General Restrictions” on page 3 lists other restrictions.

| Configuring a JMP Region

4 IMS Java User’s Guide

| Configuring a JBP Region

| PROCLIB member DFSJVMAP: The member name must be DFSJVMAP.

| DFSJVMAP is a member contained in a data set that is concatenated in the

Chapter 2. Setting Up Your Environment for IMS Java 5

| IMS Installation Verification

| DFSIVP37 is the PSB name.

6 IMS Java User’s Guide

Chapter 2. Setting Up Your Environment for IMS Java 7

| WebSphere for z/OS System Requirements

| “System Requirements for All Environments” on page 3 lists other requirements.

| WebSphere for z/OS Restrictions

8 IMS Java User’s Guide

| “General Restrictions” on page 3 lists other restrictions.

| WebSphere for z/OS Configuration

| To configure WebSphere for z/OS to access IMS databases:

| Configuring the WebSphere for z/OS J2EE Server to Locate the

Chapter 2. Setting Up Your Environment for IMS Java 9

| Deploying an Instance of the IMS JDBC Resource Adapter

| To deploy an instance of the IMS JDBC Resource Adapter:

10 IMS Java User’s Guide

| Two Strategies for Deploying Instances of IMS JDBC Resource Adaptor: