ims java users guide

IMS Version 7

IMS Java User’s Guide

SC27-0832-02

��

NoteBefore 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 softcopyformat only. The technical changes for this version are summarized under “Summary of Changes” on page xvii. Thetechnical 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 Contractwith IBM Corp.

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . vii

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiTrademarks . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . xvPrerequisite Knowledge . . . . . . . . . . . . . . . . . . . . . . xvChange Indicators . . . . . . . . . . . . . . . . . . . . . . . . xv

Summary of Changes . . . . . . . . . . . . . . . . . . . . . xviiChanges to The Current Edition of This Book for IMS Version 7 . . . . . . xviiLibrary Changes for IMS Version 7 . . . . . . . . . . . . . . . . . xvii

Chapter 1. Overview of IMS Java . . . . . . . . . . . . . . . . . . 1Design Process . . . . . . . . . . . . . . . . . . . . . . . . . 1IMS Environment Overview . . . . . . . . . . . . . . . . . . . . . 1WebSphere for z/OS Environment Overview . . . . . . . . . . . . . . 2CICS Environment Overview . . . . . . . . . . . . . . . . . . . . 2DB2 Environment Overview. . . . . . . . . . . . . . . . . . . . . 2

Chapter 2. Setting Up Your Environment for IMS Java. . . . . . . . . . 3System Requirements for All Environments . . . . . . . . . . . . . . . 3General Restrictions . . . . . . . . . . . . . . . . . . . . . . . 3IMS Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

IMS System Requirements . . . . . . . . . . . . . . . . . . . . 4IMS Restrictions . . . . . . . . . . . . . . . . . . . . . . . . 4IMS Configuration . . . . . . . . . . . . . . . . . . . . . . . 4

Configuring a JMP Region . . . . . . . . . . . . . . . . . . . 4Configuring a JBP Region . . . . . . . . . . . . . . . . . . . 5

IMS Installation Verification . . . . . . . . . . . . . . . . . . . . 6WebSphere for z/OS Setup . . . . . . . . . . . . . . . . . . . . . 8

WebSphere for z/OS System Requirements. . . . . . . . . . . . . . 8WebSphere for z/OS Restrictions . . . . . . . . . . . . . . . . . 8WebSphere for z/OS Configuration . . . . . . . . . . . . . . . . . 9

Configuring the WebSphere for z/OS J2EE Server for IMS Access . . . . 9Configuring the WebSphere for z/OS J2EE Server to Locate the IMS JDBC

Resource Adapter . . . . . . . . . . . . . . . . . . . . . 9Deploying an Instance of the IMS JDBC Resource Adapter . . . . . . 10Deploying an EJB onto a WebSphere for z/OS J2EE Server . . . . . . 11

WebSphere for z/OS Installation Verification . . . . . . . . . . . . . 12CICS Setup . . . . . . . . . . . . . . . . . . . . . . . . . . 13

CICS System Requirements . . . . . . . . . . . . . . . . . . . 13CICS Restrictions . . . . . . . . . . . . . . . . . . . . . . . 13CICS Configuration . . . . . . . . . . . . . . . . . . . . . . 13Installation Verification . . . . . . . . . . . . . . . . . . . . . 14

DB2 Setup . . . . . . . . . . . . . . . . . . . . . . . . . . 15DB2 System Requirements . . . . . . . . . . . . . . . . . . . 15DB2 Restrictions . . . . . . . . . . . . . . . . . . . . . . . 15DB2 Configuration. . . . . . . . . . . . . . . . . . . . . . . 15

ENVAR Settings for the JAVAENV Data Set . . . . . . . . . . . . 16DB2 Installation Verification . . . . . . . . . . . . . . . . . . . 17

© Copyright IBM Corp. 2000, 2002 iii

||||

||||

||||||||||||

|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

DLIModel Utility Setup . . . . . . . . . . . . . . . . . . . . . . 19Preparing the DLIMODEL MVS Procedure . . . . . . . . . . . . . . 19Preparing to Run From the MVS USS Prompt . . . . . . . . . . . . 21

Chapter 3. Accessing an IMS Database . . . . . . . . . . . . . . . 23Introduction to the Example Environment . . . . . . . . . . . . . . . 23JDBC Access Method . . . . . . . . . . . . . . . . . . . . . . 24

Describing Your IMS Databases to IMS Java . . . . . . . . . . . . . 24Using JDBC to Access an IMS Database . . . . . . . . . . . . . . 27

Classes and Field Names . . . . . . . . . . . . . . . . . . . 27PCB-Qualifying SQL Queries. . . . . . . . . . . . . . . . . . 28Writing an Application that Uses JDBC . . . . . . . . . . . . . . 29

Supported Data Types in IMS Java . . . . . . . . . . . . . . . . 32General Mappings from COBOL Copybook Types to IMS Java and Java Data

Types . . . . . . . . . . . . . . . . . . . . . . . . . . 33Supported SQL Grammar . . . . . . . . . . . . . . . . . . . . . 34

SELECT . . . . . . . . . . . . . . . . . . . . . . . . . . 35Segment-Qualifying Fields. . . . . . . . . . . . . . . . . . . 35

FROM . . . . . . . . . . . . . . . . . . . . . . . . . . . 37WHERE . . . . . . . . . . . . . . . . . . . . . . . . . . 37INSERT . . . . . . . . . . . . . . . . . . . . . . . . . . 38DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . 39UPDATE . . . . . . . . . . . . . . . . . . . . . . . . . . 39JDBC Prepared Statements for SQL . . . . . . . . . . . . . . . . 40Recommendations for JDBC . . . . . . . . . . . . . . . . . . . 40

IMS Java Hierarchic Database Interface . . . . . . . . . . . . . . . 41Application Programming Using DLIConnection . . . . . . . . . . . . 42Creating a DLIConnection Object . . . . . . . . . . . . . . . . . 42Building SSAs . . . . . . . . . . . . . . . . . . . . . . . . 42

Accessing DL/I Data using SSAs . . . . . . . . . . . . . . . . 43

Chapter 4. Writing a Java Application Program . . . . . . . . . . . . 45IMS Applications . . . . . . . . . . . . . . . . . . . . . . . . 45

Overview of IMS Application Processing . . . . . . . . . . . . . . 45Running Java Applications. . . . . . . . . . . . . . . . . . . 46Message Queuing. . . . . . . . . . . . . . . . . . . . . . 46Reading and Writing Messages to the Message Queue in Java . . . . . 46

Building an IMS Java Application by Example . . . . . . . . . . . . 46Using IMS Java to Build a Message Processing Application . . . . . . 46

Programming Models for IMS Java Applications . . . . . . . . . . . . 49JMP Programming Models . . . . . . . . . . . . . . . . . . 50JBP Programming Models . . . . . . . . . . . . . . . . . . . 51

Additional Programming Considerations . . . . . . . . . . . . . . . 52Conversational Transactions . . . . . . . . . . . . . . . . . . 52Handling Multi-Segment Messages . . . . . . . . . . . . . . . 54Coding and Accessing Messages with Repeating Structures . . . . . . 55Flexible Reading of Multiple Input Messages . . . . . . . . . . . . 56

CICS Applications . . . . . . . . . . . . . . . . . . . . . . . . 59DB2 Stored Procedures . . . . . . . . . . . . . . . . . . . . . 59

Chapter 5. DLIModel Utility . . . . . . . . . . . . . . . . . . . . 61DLIModel Utility Overview . . . . . . . . . . . . . . . . . . . . . 61Requirements and Restrictions of the DLIModel Utility . . . . . . . . . . 63

Requirements . . . . . . . . . . . . . . . . . . . . . . . . 63Restrictions . . . . . . . . . . . . . . . . . . . . . . . . . 63

Output Types of the DLIModel Utility . . . . . . . . . . . . . . . . . 64

iv IMS Java User’s Guide

||||||

|||||||||||||||||||||||||||||||||||||||||||||||||||

||

||||||

||

||||||||||||

IMS Java Metadata Classes . . . . . . . . . . . . . . . . . . . 64DLIModel Java Report . . . . . . . . . . . . . . . . . . . . . 64

PSB Description . . . . . . . . . . . . . . . . . . . . . . 64PCB Description . . . . . . . . . . . . . . . . . . . . . . 64Segment Description . . . . . . . . . . . . . . . . . . . . . 64Field Description . . . . . . . . . . . . . . . . . . . . . . 64

XMI Description of the Databases . . . . . . . . . . . . . . . . . 65DLIModel Trace . . . . . . . . . . . . . . . . . . . . . . . 66

Control Statements for the DLIModel Utility . . . . . . . . . . . . . . 66Control Data Set Rules . . . . . . . . . . . . . . . . . . . . . 66Control Statement Rules . . . . . . . . . . . . . . . . . . . . 68Control Statement Syntax . . . . . . . . . . . . . . . . . . . . 68

OPTIONS Statement. . . . . . . . . . . . . . . . . . . . . 68PSB Statement . . . . . . . . . . . . . . . . . . . . . . . 70PCB Statement . . . . . . . . . . . . . . . . . . . . . . . 70SEGM Statement . . . . . . . . . . . . . . . . . . . . . . 70FIELD Statement . . . . . . . . . . . . . . . . . . . . . . 71XDFLD Statement. . . . . . . . . . . . . . . . . . . . . . 73INCLUDE Statement . . . . . . . . . . . . . . . . . . . . . 73Comment Statement . . . . . . . . . . . . . . . . . . . . . 74

Running the DLIModel Utility . . . . . . . . . . . . . . . . . . . . 74Running the DLIModel Utility as an MVS Job . . . . . . . . . . . . . 74

PROC Statement Parameters . . . . . . . . . . . . . . . . . 75Step 1 EXEC Statement Parameters . . . . . . . . . . . . . . . 75Step 1 DD Statements . . . . . . . . . . . . . . . . . . . . 75Step 2 EXEC Statement Parameters . . . . . . . . . . . . . . . 76Step 2 DD Statements . . . . . . . . . . . . . . . . . . . . 76

Running the DLIModel Utility From MVS Unix Systems Services . . . . . 77Examples of Using the DLIModel Utility . . . . . . . . . . . . . . . . 77

Example 1. Simple Example . . . . . . . . . . . . . . . . . . . 77Example 2. Example With a Logical Relationship . . . . . . . . . . . 79Example 3. Example With a Secondary Index . . . . . . . . . . . . 83Example 4. Example with Multiple Control Statements . . . . . . . . . 85

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

How Exceptions Map to DL/I Status Codes . . . . . . . . . . . . . 91SQLExceptions . . . . . . . . . . . . . . . . . . . . . . . . 92

Sync Point Failure. . . . . . . . . . . . . . . . . . . . . . . . 93GU Message Failure . . . . . . . . . . . . . . . . . . . . . . . 93Abends. . . . . . . . . . . . . . . . . . . . . . . . . . . . 93

ABENDU0118 - Commit Failure. . . . . . . . . . . . . . . . . . 93ABENDU0475 - Batch Run Failure . . . . . . . . . . . . . . . . 94Processing Dumps . . . . . . . . . . . . . . . . . . . . . . 94

DLIModel Messages . . . . . . . . . . . . . . . . . . . . . . . 94IMSTrace . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Initiating IMSTracing . . . . . . . . . . . . . . . . . . . . . . 96Setting up Tracing for the IMS Java Library Routines . . . . . . . . . . 96Adding Trace Statements to Your Application . . . . . . . . . . . . . 97

Appendix A. Manually Creating IMS Java Metadata Classes . . . . . . . 99Mapping an IMS Database in Java Classes . . . . . . . . . . . . . . 99

IMS Database Definition (DBD) . . . . . . . . . . . . . . . . . . 99Adding Default Values for Fields of a Segment . . . . . . . . . . . . 99Mapping the PSB to DLIDatabaseView . . . . . . . . . . . . . . 100DLIDatabaseView Example . . . . . . . . . . . . . . . . . . . 101

Contents v

||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

||

||

||||||||||||

DLISegment Example . . . . . . . . . . . . . . . . . . . . . 103

Appendix B. High Performance Java . . . . . . . . . . . . . . . 105Compile and Runtime Options . . . . . . . . . . . . . . . . . . . 105Installation Verification Process . . . . . . . . . . . . . . . . . . 107

Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . 111IMS Version 7 Library . . . . . . . . . . . . . . . . . . . . . . 111

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

vi IMS Java User’s Guide

||

Figures

1. Example of a Blank IMS Installation Verification Procedure Screen . . . . . . . . . . . . . 72. Example IMS Installation Procedure Screen with Transaction Input Information . . . . . . . . 73. Example IMS Installation Verification Procedure Screen with Transaction Output Information . . . 84. Example Database Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . 245. Example PSB Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256. DBD Sample Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257. The IMS Java Summary Report . . . . . . . . . . . . . . . . . . . . . . . . . 268. IMS DB Segments and Fields with Their Corresponding DB2 Tables and Columns . . . . . . 289. PCB-Qualifying SQL Query Example . . . . . . . . . . . . . . . . . . . . . . . 29

10. JDBC Application. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3011. Establish a Database Connection. . . . . . . . . . . . . . . . . . . . . . . . . 3112. Example of SELECT Query Results . . . . . . . . . . . . . . . . . . . . . . . . 3613. Sample Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3714. Sample Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3715. Sample INSERT Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . 3816. Sample DELETE Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . 3917. Sample UPDATE Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . 3918. Creating a DLIConnection Object . . . . . . . . . . . . . . . . . . . . . . . . . 4219. Creating an SSAList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4320. Subclass IMSFieldMessage: Input Message Sample Code . . . . . . . . . . . . . . . 4721. Subclass IMSFieldMessage: Output Message Sample Code . . . . . . . . . . . . . . . 4822. Subclass IMSApplication Sample Code . . . . . . . . . . . . . . . . . . . . . . 4923. Defining a SPA Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5324. Reading the SPA Message . . . . . . . . . . . . . . . . . . . . . . . . . . . 5325. Writing the SPA Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . 5426. Example Output Message . . . . . . . . . . . . . . . . . . . . . . . . . . . 5627. Defining the Primary Input Message . . . . . . . . . . . . . . . . . . . . . . . . 5728. Creating the Input Messages . . . . . . . . . . . . . . . . . . . . . . . . . . 5829. Message Reading Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5930. The DLIModel Utility Inputs and Outputs . . . . . . . . . . . . . . . . . . . . . . 6231. Sample DLIModel Utility PROC . . . . . . . . . . . . . . . . . . . . . . . . . 7532. Physical DBD for Simple Example . . . . . . . . . . . . . . . . . . . . . . . . 7833. PSB for Simple Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7834. Minimal MVS JCL stream. . . . . . . . . . . . . . . . . . . . . . . . . . . . 7835. Control Data Set for Simple Example . . . . . . . . . . . . . . . . . . . . . . . 7836. DLIModel Java Report for Simple Example . . . . . . . . . . . . . . . . . . . . . 7937. EMPDB2 Physical DBD for Logical Relationship Example . . . . . . . . . . . . . . . . 8038. DEALDB2 Physical DBD for Logical Relationship Example . . . . . . . . . . . . . . . 8039. Logical DBD for Logical Relationship Example . . . . . . . . . . . . . . . . . . . . 8140. PSB with Field-Level Sensitivity for Logical Relationship Example . . . . . . . . . . . . . 8141. Control Data Set for Logical Relationship Example . . . . . . . . . . . . . . . . . . 8242. DLIModel Java Report for Logical Relationship Example . . . . . . . . . . . . . . . . 8243. DBD for Secondary Index Example . . . . . . . . . . . . . . . . . . . . . . . . 8344. Logical DBD for Secondary Index Example . . . . . . . . . . . . . . . . . . . . . 8445. PSB for Secondary Index Example . . . . . . . . . . . . . . . . . . . . . . . . 8446. MVS USS Command for Secondary Index Example . . . . . . . . . . . . . . . . . . 8447. Control Data Set for Secondary Index Example . . . . . . . . . . . . . . . . . . . 8448. DLIModel Java Report for Secondary Index Example . . . . . . . . . . . . . . . . . 8549. Physical DBD for Multiple Control Statements Example. . . . . . . . . . . . . . . . . 8650. PSB for Multiple Control Statements Example . . . . . . . . . . . . . . . . . . . . 8651. MVS USS Command for Control Statements Example . . . . . . . . . . . . . . . . . 8652. Top-Level Control Data Set for Multiple Control Statements Example. . . . . . . . . . . . 8753. 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 . . . . . . . . . . . . . 8955. Database access methods of DLIConnection . . . . . . . . . . . . . . . . . . . . 9256. IMSException Sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9257. Setting a Trace within a Static Method . . . . . . . . . . . . . . . . . . . . . . . 9758. Setting Up IMSTrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9759. Example Database and Segments . . . . . . . . . . . . . . . . . . . . . . . . 9960. DBD Sample Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10061. DLIDatabaseView Example Code . . . . . . . . . . . . . . . . . . . . . . . . 10262. Example DLISegment Code . . . . . . . . . . . . . . . . . . . . . . . . . . 10363. -exclude statement example . . . . . . . . . . . . . . . . . . . . . . . . . . 10664. Binding the class files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10665. Example of a Blank IMS Installation Verification Procedure Screen . . . . . . . . . . . . 10866. Example IMS Installation Procedure Screen with Transaction Input Information . . . . . . . 10867. Example IMS Installation Verification Procedure Screen with Transaction Output Information 109

viii IMS Java User’s Guide

||||

||

||||||||

Tables

1. Supported Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322. ResultSet.getxxx Methods to Retrieve JDBC Types . . . . . . . . . . . . . . . . . . 333. Mapping from COBOL to IMS and Java . . . . . . . . . . . . . . . . . . . . . . 344. DLITypeInfo Constants and Java Types based on PICTURE clause . . . . . . . . . . . . 345. CopyBook Formats Mapped to IMS Java Types . . . . . . . . . . . . . . . . . . . 346. Status Code, Reason, and Return Code . . . . . . . . . . . . . . . . . . . . . . 937. 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. IBMmay not offer the products, services, or features discussed in this document in othercountries. Consult your local IBM representative for information on the products andservices 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, orservice may be used. Any functionally equivalent product, program, or service thatdoes 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-IBMproduct, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not give you anylicense to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

IBM World Trade Asia CorporationLicensing2-31 Roppongi 3-chome, Minato-kuTokyo 106, Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSOR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIESOF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR APARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not apply toyou.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvements and/orchanges in the product(s) and/or the program(s) described in this publication at anytime without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of thoseWeb sites. The materials at those Web sites are not part of the materials for thisIBM 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 believesappropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose ofenabling: (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 informationwhich has been exchanged, should contact:

IBM CorporationJ46A/G4555 Bailey AvenueSan Jose, CA 95141-1099U.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 materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement, or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurement may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers of thoseproducts, their published announcements or other publicly available sources. IBMhas not tested those products and cannot confirm the accuracy of performance,compatibility or any other claims related to non-IBM products. Questions on thecapabilities of non-IBM products should be addressed to the suppliers of thoseproducts.

All statements regarding IBM’s future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

This information is for planning purposes only. The information herein is subject tochange before the products described become available.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

COPYRIGHT LICENSE:

This information contains sample application programs in source language, whichillustrates 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 programsconforming to the application programming interface for the operating platform forwhich the sample programs are written. These examples have not been thoroughlytested under all conditions. IBM, therefore, cannot guarantee or imply reliability,serviceability, or function of these programs. You may copy, modify, and distributethese sample programs in any form without payment to IBM for the purposes ofdeveloping, using, marketing, or distributing application programs conforming toIBM’s application programming interfaces.

xii IMS Java User’s Guide

Each copy or any portion of these sample programs or any derivative work, mustinclude 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 rightsreserved.

If you are viewing this information softcopy, the photographs and color illustrationsmay not appear.

TrademarksThe following terms are trademarks of the IBM Corporation in the United States orother countries or both:

BookManagerDB2CICSIBMIMS

MVSOS/390WebSpherez/OS

Java and all Java-based trademarks and logos are trademarks of SunMicrosystems, Inc., in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Other company, product, and service names may be trademarks or service marksof 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 towrite Java application programs that access IMS databases.

This softcopy book is available only in PDF and BookManager formats. This book isavailable on the IMS Version 7 Licensed Product Kit (LK3T-3526). You can also getthe most current versions of the PDF and BookManager formats by going to theIMS Web site at www.ibm.com/ims and linking to the Library page.

Prerequisite KnowledgeTo configure your system for IMS Java, you must understand system administrationfor your system (IMS, WebSphere Application Server, CICS, or DB2). For IMSsystem administration, you should know the concepts in IMS Version 7Administration Guide: System.

To create IMS Java metadata classes, which is a required step in writing IMS Javaapplications, you must understand IMS databases. IMS database concepts aredescribed in IMS Version 7 Administration Guide: Database Manager.

To write IMS Java applications, you must thoroughly understand the Java languageand JDBC. This book assumes that you know Java and JDBC. It does not explainany Java or JDBC concepts.

Change IndicatorsTechnical changes are indicated in this publication by a vertical bar ( | ) to the left ofthe 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 7This edition, which is available in softcopy format only, includes technical andeditorial changes.

This book has undergone major organizational changes in addition to technicalchanges.

This book contains new information about the following enhancements to IMS Javaapplication 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 Serverz/OS, and DB2 UDB for z/OS and OS/390 Stored Procedures support

Library Changes for IMS Version 7The major change to the IMS Version 7 library is that it is available not only inhardcopy and in softcopy on BookManager, but also in softcopy Portable DocumentFormat (PDF). The complete library is available in BookManager and PDF on theIMS Version 7 product kit CD-ROM (LK3T-3526). The unlicensed IMS Version 7softcopy 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 andPDF 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 Guideand Reference

The book formerly titled IMS/ESA Common Queue Server Guide and Referencein the Version 6 library is called IMS Version 7 Common Queue Server and BasePrimitive Environment Guide and Reference.

The IMS Version 7 Common Queue Server and Base Primitive EnvironmentGuide 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 EnvironmentGuide 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 iscalled 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 andIMS/ESA Utilities Reference: Transaction Manager in the Version 6 library havebeen combined into one book called IMS Version 7 Utilities Reference: Databaseand Transaction Manager.

v IMS Version 7 Application Programming: Database Manager and IMS Version 7Customization Guide

© Copyright IBM Corp. 2000, 2002 xvii

|

||

||

||

||

|

||

||

||||||||

|

||

|||

|||

||

|

||

|

||||

||

The chapter titled ″IMS Adapter for REXX Exit Routine″ has been moved fromthe IMS Version 7 Application Programming: Database Manager to the IMSVersion 7 Customization Guide.

v IMS Version 7 Sample Operating Procedures

For IMS Version 7, this book is available only in BookManager and PDF softcopyon 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). Asa new book, the IJUG is available only in PDF and BookManager softcopy on theproduct 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 Javaapplication programs that access IMS databases from IMS, WebSphere ApplicationServer for z/OS and OS/390, CICS Transaction Server for z/OS, or DB2 UDB forz/OS and OS/390 Stored Procedures.

IMS Java application programs use JDBC or the IMS Java hierarchic databaseinterface. JDBC is the SQL-based standard interface for data access in the Java 2SDK Standard Edition and Enterprise Edition. IMS Java’s implementation of JDBCsupports a selected subset of the full facilities of the JDBC 2.0 API. The IMS Javahierarchic database interface is more closely related to the standard DL/I databasecall interface used with other languages, and provides a lower-level access to IMSdatabase functions than the JDBC interface.

IMS Java provides class libraries that allow you to easily develop applications thatcan 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 andcan 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 theIMS databases the same way.

Design Process1. Determine what database information the application needs to process.

2. Create the IMS Java metadata classes based on the PSB using the DLIModelutility.

The IMS database administrator, in addition to generating the PSB, also runsthe DLIModel utility to create the IMS Java Metadata classes for the Javaapplication developer to use to write the application program.

3. Write the application program. The DLIModel Java Report, generated by theDLIModel utility, provides the information about the IMS database.

4. Configure environment and deploy application.

IMS Environment OverviewIMS Java application programs run in one of two IMS dependent regions, whichprovide 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 toMessage 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 inputmessages, 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 7Application Programming: Design Guide.

v For information on configuring JMP and JBP regions, see “IMS Setup” on page 4and IMS Version 7 Installation Volume 2: System Definition and Tailoring.

WebSphere for z/OS Environment OverviewYou can write IMS Java applications that run on a WebSphere Application Serverfor z/OS and OS/390 J2EE server and access IMS databases. When WebSpherefor z/OS and IMS DB are on the same operating system image, the IMS Javaapplication—a WebSphere for z/OS Enterprise Java Bean (EJB)—accesses IMSdatabases using the Open Database Access (ODBA) interface.

Related Reading: For information on configuring WebSphere for z/OS to run IMSJava applications, see “WebSphere for z/OS Setup” on page 8.

CICS Environment OverviewYou can write IMS Java applications that run on CICS Transaction Server for z/OSand access IMS databases.

Related Reading:

v For information on configuring CICS to runs IMS Java applications, see “CICSSetup” on page 13.

v For information on developing an IMS Java application that runs on a CICSTransaction Server, see “CICS Applications” on page 59.

DB2 Environment OverviewYou can write DB2 UDB for z/OS and OS/390 Stored Procedures that access IMSdatabases.

Related Reading:

v For information on configuring DB2 to run IMS Java applications, see “DB2Setup” on page 15.

v For information on developing an IMS Java application that runs as a DB2 storedprocedure, 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, WebSpherefor z/OS, CICS, and DB2 is discussed in this chapter. The first two sections,“System Requirements for All Environments” and “General Restrictions”, apply to allenvironments. Environment-specific requirements and restrictions, and configurationand 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 EnvironmentsTo use IMS Java to write application programs that access IMS databases, thefollowing software is required:

v IBM Developer Kit for OS/390, Java 2 Technology Edition with the PersistentReusable 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 preparingHFS, 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 RestrictionsFor all environments, IMS Java supports only the AIB interface; therefore, thedatabase PCBs in your PSBGEN must be explicitly named.

An IMS Java application may use path calls to access hierarchic paths ofsegments. Therefore, your PSBs may need to specify the P processing option forsome or all segments. See Chapter 3, “Accessing an IMS Database” on page 23 formore information.

IMS does not support local transactions. Therefore, the commit, rollback, andsetAutoCommit methods on an IMS Java JDBC Connection object are notsupported 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 SetupThis section describes the system requirements, restrictions, configuration, andinstallation verification specific to the IMS environment.

IMS System RequirementsJava applications running in an IMS JMP or JBP region do not require anyadditional system requirements other than the requirements listed in “SystemRequirements for All Environments” on page 3.

IMS RestrictionsJMP 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 ConfigurationThis section gives the steps to configure JMP and JBP IMS Java dependentregions.

Related Reading:

v For detailed information on DFSJBP and DFSJMP procedures, used to start JVMdependent regions, see IMS Version 7 Installation Volume 2: System Definitionand Tailoring.

v For details about master JVMs and worker JVMs, and for a complete list ofpossible JVM options, see IBM Developer Kit for OS/390, Java 2 TechnologyEdition: New IBM Technology featuring Persistent Reusable Java VirtualMachines.

Configuring a JMP RegionTo run IMS Java applications in a JMP region, the region must be initialized withspecific JVM options. Specify the following parameters:

JVMOPMAS=member nameRequired parameter specifies the name of the member in IMS.PROCLIB thatcontains the JVM options for the master JVM. The master JVM defines theclass cache for its associated worker JVMs.

A sample member, called DFSJVMMS (master JVM options member), issupplied in the IMS sample library SDFSISRC. DFSJVMMS contains a subsetof 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. Separatethe path names with a colon and with no spaces. The greater-than symbol(>) acts as a nest-line extension.


|

|

|

||

||

|

|||

|

|

|

|

|

|

||

|

|||

||||

|||

||||

|||

|

||||

If your .class files are contained in a .jar file, then the absolute path nameto 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 theruntime libraries for IMS Java.

JVMOPWKR=member nameOptional parameter specifies the name of the member in IMS.PROCLIB thatcontains the JVM options for the worker JVM. The worker JVM is created in thesame address space as its master JVM. It uses the class cache defined by themaster JVM.

There is a sample member, called DFSJVMWK (worker JVM options member),supplied in the IMS sample library. DFSJVMWK contains a subset of thepossible JVM options.

ENVIRON=member nameRequired parameter specifies the name of a data set member that isconcatenated 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 nospace between the equal sign (=) in LIBPATH= and the beginning of the first pathname. 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 youare using the default IMS Java directory, enter /usr/lpp/ims/imsjava71.

Example: If you code ENVIRON=DFSENV on your JMP or JBP procedure, theDFSENV member must reside in IMS.PROCLIB or its equivalent. It mustcontain 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 RegionTo run IMS Java applications in a JBP region, initialize the region with the followingJVM options. Specifically, the following new procedure parameters are needed toinitialize a JBP region:

JVMOPMAS=member nameFor details see JVMOPMAS= for the JMP procedure under “Configuring a JMPRegion” on page 4.

ENVIRON=member nameFor details see ENVIRON= for the JMP procedure under “Configuring a JMPRegion” 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 thePROCLIB DD. A sample member, DFSJVMAP is supplied in the IMS sample library,SDFSISRC.

IMS Setup

Chapter 2. Setting Up Your Environment for IMS Java 5

||

||||

|||||

|||

|||

|

|||

|

||

|||

|||||||

||||

|||

|||

|

|||

Member DFSJVMAP is optional and is read during dependent region applicationscheduling, making it a dynamic member. You do not need to shut down IMS whenadding application name mappings to DFSJVMAP for the changes to take affect.Member DFSJVMAP maps all of the 8-byte (or less), uppercase IMS Javaapplication names that are specified to IMS to the true OMVS path name for theIMS Java application.class file.

IMS Installation VerificationTo verify that IMS Java is installed properly in an IMS environment:

1. Expand the file samples.tar. For instructions on expanding this file, see theReadme file in the samples directory.

2. Set the following four JVM members in IMS.PROCLIB (created at systemgeneration), as follows:

v DFSJVMAPDFSIVP37=samples/ivp/ims/IMSIVP

DFSIVP37 is the PSB name.

v DFSJVMEVLIBPATH=/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 aslibJavTDLI.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. TheJCL must contain the following:

v Four IMS.PROCLIB members defined in step 2

v JAVAOUT and JAVAERR DD statements to allow standard output andstandard 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 notexist in the specified directory.

5. From the IMS terminal, invoke the formatted screen for the transaction byissuing the following command:/format IVTCM

IMS Setup


||||||

|

|

||

||

|

|

|

|

|

||

|

||

||||||||

|

||||

|

||

|

||

||

||

||

|

An input screen as shown in Figure 1 is displayed.

6. Enter DISPLAY for PROCESS CODE and LAST1 for LAST NAME. Figure 2shows an example for the display query.If IMS Java is properly installed, the output shown in Figure 3 on page 8 is

displayed.

*************************************************** IMS INSTALLATION VERIFICATION PROCEDURE ***************************************************

TRANSACTION TYPE : CONVERSATIONALDATE : 04/03/00

PROCESS CODE (*1) :(*1) PROCESS CODE

LAST NAME : ADDDELETE

FIRST NAME : UPDATEDISPLAY

EXTENSION NUMBER : TADDEND

INTERNAL ZIP CODE :

SEGMENT# :

Figure 1. Example of a Blank IMS Installation Verification Procedure Screen



PROCESS CODE (*1) : DISPLAY(*1) PROCESS CODE

LAST NAME : LAST1 ADDDELETE



INTERNAL ZIP CODE :

SEGMENT# :

Figure 2. Example IMS Installation Procedure Screen with Transaction Input Information

IMS Setup


|||||||||||||||||||||||||

|||||||||||||||||||||||||

||

||||

||

WebSphere for z/OS SetupThis section assumes you are familiar with WebSphere Application Server for z/OSand OS/390, its Administration application, and its Application Assembly tool.

Related Reading:

v For detailed information about how to use the Administration application, seeWebSphere Application Server V4.0.1 for z/OS and OS/390 : SystemManagement User Interface.

v For detailed information about assembling and deploying an EJB onto a J2EEserver, 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 RequirementsAccess to IMS databases from WebSphere applications requires WebSphereApplication Server for z/OS and OS/390 V4.0.1 or higher and additional WebSphereApplication Server z/OS Connection Management support.

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

WebSphere for z/OS RestrictionsThe following restrictons apply to WebSphere for z/OS EJBs for accessing IMSdatabases:

v IMS Java does not support container-managed signon or component-managedsignon.

v The java.sql.Connection object must be acquired, used, and closed within atransaction method.

v A global transaction must exist before creating a Statement orPreparedStatement object from a JDBC connection. Either specifycontainer-demarcated transactions in the EJB deployment descriptor or explicitly





FIRST NAME : FIRST1 UPDATEDISPLAY

EXTENSION NUMBER : 8-111-1111 TADDEND

INTERNAL ZIP CODE : D01/R01

Person found! SEGMENT# :

Figure 3. Example IMS Installation Verification Procedure Screen with Transaction OutputInformation

WebSphere for z/OS Setup


||||||||||||||||||||||||||||

||

|

|||

|||

|

|||

|

|

||

||

||

|||

begin a global transaction by calling javax.transaction.UserTransaction.begin inthe EJB method before creating a Statement or PreparedStatement object.


WebSphere for z/OS ConfigurationTo deploy an EJB on a WebSphere for z/OS J2EE server, you must perform thefollowing 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 JDBCResource 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 AccessTo run an EJB on a WebSphere for z/OS J2EE server, you must configureWebSphere for z/OS to access IMS databases using ODBA. ODBA uses thedatabase resource adapter (DRA) to access IMS databases. More details about thesteps in this section are in IMS Version 7 Installation Volume 2: System Definitionand 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 willrun by adding the load library that contains the DRA start up table and ODBAruntime code to the STEPLIB.

Configuring the WebSphere for z/OS J2EE Server to Locate theIMS JDBC Resource AdapterYou must configure the WebSphere for z/OS J2EE server for the IMS JDBCResource Adapter (also referred to as the IMS JDBC Connector). The procedure isdescribed in this section. Activating a conversation sets the sysplex and J2EEproperties for the IMS JDBC Resource Adapter. Expanding the custom service fileand entering its directory in the file jvm.properties allows WebSphere for z/OS toinitialize and terminate ODBA.

Important: If you do not edit the jvm.properties file correctly, PSB allocation failswhen using the IMS JDBC Resource Adapter.

To configure the WebSphere for z/OS J2EE server to locate the IMS JBDCResource Adapter:

1. Create a conversation and define the IMS JDBC Resource Adapter as a J2EEresource:

a. Open the WebSphere Application Server for z/OS and OS/390Administration 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 LIBPATHenvironment variables:



||

|

|

||

|

||

|

||

||||||

|

|

|

|||

||||||||

||

||

||

||

|

|

|

||

v For the CLASSPATH environment variable, enter the full name of thedirectory 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 IMSJava 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 defaultdirectory 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 directoryas the imsjava71.rar file:

v IMSJdbcCustomService.xml

v howto.html

Related Reading: For more information about IMS JDBC Resource Adapterconfiguration, 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, expandimsjava71.rar on your desktop.

3. Edit the jvm.properties file for WebSphere J2EE server regions that will accessIMS databases to identify the location of the file IMSJdbcCustomService.xml.

To edit the jvm.properties file, add the directory where the fileIMSJdbcCustomService.xml is to the preconfigured custom services in thejvm.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 AdapterConfiguring and deploying an instance of the IMS JDBC Resource Adapter createsa data source for an EJB. Deploy a new instance for each database or databaseresource adapter (DRA) startup table an EJB accesses. See “Two Strategies forDeploying Instances of IMS JDBC Resource Adaptor” on page 11 for moreinformation on when to deploy a new instance.

Note: If you are setting up WebSphere for the first time and want to verify yourinstallation, start the procedure in the following section “WebSphere for z/OSInstallation 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 Administrationtool.

2. Add a conversation.

3. Navigate to the sysplex that will run the EJBs.

The following folders are displayed:J2EEServersServersSystemsJ2EE Resources



||

||

||

||

|

|||

|

||

|

|

||||

||

|||

|

||

||||||

|||

|

||

|

|

|||||

Logical Resource Mapping

4. Add a J2EE resource. The resource name is your choice. The type isIMSJdbcDataSource.

5. Add a J2EE resource instance. The name is your choice.

6. Enter the DRA startup table name and optionally the DLIDatabaseView subclassname. To decide whether to add a DLIDatabaseView subclass name, see “TwoStrategies for Deploying Instances of IMS JDBC Resource Adaptor”.

7. Save and activate the conversation.

Note: These instructions use two conversations to deploy the IMS JDBCResource Adapter and the Enterprise Archive (EAR). However, you canalso deploy an EAR in the same conversation that deploys the IMSJDBC Resource Adapter instance.

Two Strategies for Deploying Instances of IMS JDBC Resource Adaptor:When configuring an instance of the IMS JDBC Resource Adapter, you canoptionally set the DLIDatabaseView subclass name.

If you do set the subclass name, you must create a new instance of the IMS JDBCResource Adapter for every database an EJB accesses. You can override theDLIDatabaseView subclass name (set in step 6) in the DataSource object by callingthe 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 theIMS JDBC Resource Adapter for each DRA startup table. In the EJB, define theDLIDatabaseView subclass name (set in step 6) in the DataSource object by callingthe setDatabaseView method and providing the fully-qualified name of the subclass.

Deploying an EJB onto a WebSphere for z/OS J2EE ServerAfter 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 toolsuch as Websphere Studio Application Developer Integrated Edition.

2. Import the EAR into WebSphere for z/OS and OS/390 Application Assemblytool.

3. Create a resolved EAR suitable for deploying on a WebSphere for z/OS J2EEserver.

4. Open the WebSphere Application Server for z/OS and OS/390 Administrationapplication.

5. Add a conversation.

6. Navigate to the J2EEServers folder of the sysplex that will run the EJB.

The following folders are displayed:J2EEServersServersSystemsJ2EE ResourcesLogical Resource Mapping

7. Expand the J2EEServers folder and choose the server to install the EJB on.

8. Install the EJB.

a. Specify the fully-qualified directory name of the EAR and the FTP server ofthe 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 IMSJDBC Resource Adapter” on page 10.

9. Save and activate the conversation.

WebSphere for z/OS Installation VerificationAfter you have configured WebSphere for z/OS to access IMS (“Configuring theWebSphere for z/OS J2EE Server for IMS Access” on page 9) and to locate theIMS JDBC Resource Adapter (“Configuring the WebSphere for z/OS J2EE Server toLocate the IMS JDBC Resource Adapter” on page 9), you can verify that yoursystems are configured correctly by running the installation verification program(IVP).

Note: You can also use this procedure to install the dealership sample EAR, whichis also in samples.tar. The sample file name is imsjavaDealership.ear andthe DLIDatabaseView subclass name issamples.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 thesamples directory.

b. Use FTP to transfer the file imsjavaIVP.ear to your workstation.

2. Deploy an instance of the IMS JDBC Resource Adapter:

a. Open the WebSphere Application Server for z/OS and OS/390Administration tool.


c. Navigate to the sysplex that will run the EJBs.


d. Add a J2EE resource. The resource name is your choice. The type isIMSJdbcDataSource.

e. Add a J2EE resource instance with the following information:

v J2EE Resource Instance Name: your choice, such asIMSJavaIVPDataSource

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

b. Create a resolved EAR suitable for deploying on a WebSphere for z/OSJ2EE server.

4. Deploy the IVP EAR, which contains the IVP JAR file and the IVP Web Archive(WAR):

a. Open the WebSphere Application Server for z/OS and OS/390Administration application.




||

|

|

||||||

||||

|

||

|

|

||

|

|

||||||

||

|

||

|

|

|

|

|

||

||

||

||

|

c. Navigate to the J2EEServers folder of the sysplex that will run the EJB.


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 forthe 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 RequirementsTo run Java application programs in a CICS environment, you must have CICSTransaction Server for z/OS Version 2.


CICS RestrictionsIn a CICS environment, only one PSB can be allocated at a time. Therefore, anapplication can only have one active JDBC connection at a time. The applicationmust close the JDBC connection before opening another JDBC connection.“General Restrictions” on page 3 lists other restrictions.

CICS ConfigurationTo configure CICS for IMS Java, modify the CICS JVM profile DFHJVMPR. Thedefault 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 trustedmiddleware:



|

||||||

|

|

|

|

|

|

|

|

|

||

|

|

|

|

|

|

|

||

|

||

|

|

||||

|

||

|

||

a. Add either a TMPREFIX or TMSUFFIX variable. The TMPREFIX adds thelibraries at the head of the middleware path and TMSUFFIX adds thelibraries 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 filelibJavTDLI.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 CICSJVM profile). Point this classpath to the locations of the user applications. Forexample:ibm.jvm.shareable.application.class.path=/imsjava/myApplication

Related Reading: For detailed information on CICS system definition, see CICSTransaction Server for OS/390: CICS System Definition Guide.

Installation VerificationAfter you configure CICS to run IMS Java applications, verify that IMS Java isinstalled correctly and that CICS is configured correctly to run IMS Javaapplications.

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 JVMPROPSvariable 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 onthe CICS terminal is converted to uppercase. However, the IVP JVM class (withthe 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 theJVM class.

PROGram ==> cicsivp (or whatever program name you choose)Group ==> ivp (or whatever group name you choose)COncurrency ==> ThreadsafeJVM ==> YesJVMClass ==>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 (suchas CICSIVP).

a. On the CICS terminal, type CEDA DEFINE TRANSACTION

b. Fill in only the transaction, program (defined above), and group (same asprogram’s group):

CICS Setup


|||

|

|

|

||

|

|

||||

|

||

|

|||

|

|||

|

||||

|

|

|

|

||

||||||

|

||

|

||

TRANSaction ==> civpGroup ==> ivpPROGram ==> 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 => cicsivpGroup => 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 => civpGroup => 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 RequirementsAccess to IMS databases from DB2 Stored Procedures requires DB2 UDB for z/OSand OS/390 Version 7 with APARs PQ46673 and PQ50443. You also must have theDB2 for OS/390 and z/OS SQLJ/JDBC driver with APAR PQ48383 installed.


DB2 RestrictionsIn a WLM-managed stored procedure address space configured to run LANGUAGEJAVA stored procedures, a considerable amount of storage is used for the JavaVirtual Machine. The NUMTCB parameter must be adjusted accordingly. Therecommended NUMTCB is a maximum of 7.


DB2 ConfigurationThe stored procedures must be compiled (javac) by JDK 1.3.1.

The following is an example JCL procedure of a Java WLM-established addressspace://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

CICS 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 proceduretable

3. Your HLQ.TNUC0 is a data set that contains the DRA start-up table

ENVAR Settings for the JAVAENV Data SetThe 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 ofHFS directories that is searched for Java class files when the storedprocedures 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 defaultIMS Java directory, specify:TMSUFFIX=/usr/lpp/ims/imsjava71/imsjava.jar

The JAVAENV data set should have the following attributes:Organization . . . : PSRecord format . . . : VBRecord length . . . : 1028Block 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 toSYSIBM.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’)//SYSPRINT DD SYSOUT=*//SYSUDUMP DD SYSOUT=*//SYSIN DD *

CREATE PROCEDURE yourJavaStoredProcedureName(VARCHAR(20) IN,VARCHAR(1000) OUT)

FENCEDNO SQLLANGUAGE JAVADYNAMIC RESULT SET 0EXTERNAL NAME ’packageName.ClassName.methodEntryName’PARAMETER STYLE JAVACOLLID DSNJDBCWLM ENVIRONMENT your_WLM_Environment_Name;GRANT EXECUTE ON PROCEDURE yourJavaStoredProcedureName TO PUBLIC;

The following is a sample JCL to delete your stored procedure fromSYSIBM.SYSROUTINES://DELETJSP JOB ,’YOUR NAME’,// MSGCLASS=H,TIME=3,USER=SYSADM,PASSWORD=XXXXXXXX,// MSGLEVEL=(1)//*************************************************************//* Change xx in the PLAN(DSNTIAxx) to your DB2 version,//* such as 71 or 81//**************************************************************//JOBLIB DD DISP=SHR,DSN=CEE.SCEERUN// DD DISP=SHR,DSN=DB2HLQ.DSNEXIT// DD DISP=SHR,DSN=DB2HLQ.SDSNLOAD//PH061S01 EXEC PGM=IKJEFT01,DYNAMNBR=20//SYSTSPRT DD SYSOUT=*//SYSTSIN DD *

DSN SYSTEM(your_DB2_subsystem_name)RUN PROGRAM(DSNTIAD) PLAN(DSNTIA71) -

LIB(’DB2HLQ.RUNLIB.LOAD’) -PARM(’RC0’)

//SYSPRINT DD SYSOUT=*//SYSUDUMP DD SYSOUT=*//SYSIN DD *

DROP PROCDURE yourJavaStoredProcedureName RESTRICT;

DB2 Installation VerificationThe following is sample code of the DB2 Client and DB2 Stored Procedure classesfor 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’,// MSGCLASS=H,TIME=3,// USER=SYSADM,PASSWORD=XXXXXXXX,// MSGLEVEL=(1)//******************************************************************************//* Change xx in the PLAN(DSNTIAxx) to your DB2 version//* such as: 71 or 81//******************************************************************************//CREATJSP EXEC PGM=IKJEFT01,DYNAMNBR=20//STEPLIB DD DISP=SHR,DSN=DB2HLQ.DSNEXIT// DD DISP=SHR,DSN=DB2HLQ.SDSNLOAD//SYSTSPRT DD SYSOUT=*//SYSTSIN DD *DSN SYSTEM(DB2_Subsystem_Name)RUN PROGRAM(DSNTIAD) PLAN(DSNTIAxx) -LIB(’DB2HLQ.RUNLIB.LOAD’) -PARM(’RC0’)

//SYSPRINT DD SYSOUT=*//SYSUDUMP DD SYSOUT=*//SYSIN DD *

CREATE PROCEDURE IVPStoredProc(VARCHAR (50) IN,VARCHAR (200) OUT,VARCHAR(500) OUT)

FENCEDNO SQLLANGUAGE JAVADYNAMIC RESULT SET 0EXTERNAL NAME ’samples.ivp.db2.DB2IvpStoredProcedure.execute’PARAMETER STYLE JAVACOLLID DSNJDBCWLM ENVIRONMENT Your_WLM_Environment_Name;GRANT EXECUTE ON PROCEDURE IVPStoredProc TO PUBLIC;

3. Submit the following JCL to create a plan for the client program://BNDIVPCL JOB ,’YOUR NAME’,// MSGCLASS=H,TIME=3,// USER=SYSADM,PASSWORD=XXXXXXXX,// MSGLEVEL=(1)//*********************************************************************//* Change xx in the PLAN(DSNTEPxx) to your DB2 version//* such as: 71 or 81//*********************************************************************//BINDCLNT EXEC PGM=IKJEFT01,DYNAMNBR=20//STEPLIB DD DISP=SHR,DSN=DB2HLQ.DSNEXIT// DD DISP=SHR,DSN=DB2HLQ.SDSNLOAD//DBRMLIB DD DISP=SHR,DSN=DB2HLQ.SDSNDBRM//SYSTSPRT DD SYSOUT=*//SYSPRINT DD SYSOUT=*//SYSUDUMP DD SYSOUT=*//SYSTSIN DD *

DSN SYSTEM(DB2ID)BIND PACKAGE (DSNJDBC) MEMBER(DSNJDBC1) ISOLATION(UR) -ACTION(REPLACE) VALIDATE(BIND)BIND PACKAGE (DSNJDBC) MEMBER(DSNJDBC2) ISOLATION(CS) -ACTION(REPLACE) VALIDATE(BIND)BIND PACKAGE (DSNJDBC) MEMBER(DSNJDBC3) ISOLATION(RS) -ACTION(REPLACE) VALIDATE(BIND)BIND PACKAGE (DSNJDBC) MEMBER(DSNJDBC4) ISOLATION(RR) -ACTION(REPLACE) VALIDATE(BIND)BIND PLAN(DB2IVPCL) KEEPDYNAMIC(YES) ACTION(REPLACE) -

PKLIST(DSNJDBC.DSNJDBC1, -DSNJDBC.DSNJDBC2, -DSNJDBC.DSNJDBC3, -DSNJDBC.DSNJDBC4)

RUN PROGRAM(DSNTEP2) PLAN(DSNTEPxx) -LIB(’DB2HLQ.RUNLIB.LOAD’)

END

DB2 Setup


|||||||||||||||||||||||||||||||

|

|||||||||||||||||||||||||||||||||

//SYSIN DD *GRANT EXECUTE ON PLAN DB2IVPCL TO PUBLIC;/*//

4. For USS, create a file named db2sqljjdbc.properties that contains thefollowing:DB2SQLJSSID=yourDB2IDDB2SQLJPLANNAME=DB2IVPCLDB2SQLJATTACHTYPE=RRSAFDB2SQLJDBRMLIB=DB2HLQ.SDSNDBRM

The location of this file is pointed to by the environment variableDB2SQLJPROPERTIES.

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.zipexport CLASSPATH=$CLASSPATH:$SQLJ_HOME/classes/db2sqljruntime.zipexport CLASSPATH=$CLASSPATH:$SQLJ_HOME/classes/db2sqljclasses.zipexport CLASSPATH=$CLASSPATH:/usr/lpp/ims/imsjava71/imsjava.jarexport CLASSPATH=$CLASSPATH:$JAVA_HOME/lib:.

export LIBPATH=$SQLJ_HOME/lib:$JDBC_HOME/libexport LIBPATH=:$JAVA_HOME/lib:$LIBPATH

export LD_LIBRARY_PATH=.:$SQLJ_HOME/bin:$JDBC_HOME/libexport 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 SetupBefore the DLIModel utility can be run, from the MVS USS prompt or by runningJCL, some preparation is required. Since DLIModel is a Java application, thispreparation depends on the Java environment in your installation. Guidelines areprovided here, but they may require modification in order to fit your environment.

Preparing the DLIMODEL MVS ProcedureThe DLIMODEL procedure is delivered as member DFSMODEL in the IMSdistribution library SDFSISRC. To prepare this procedure, perform the followingsteps:

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

DB2 Setup


||||

||

||||

||

|

||||||||||||||||||||||

||

|

||

||

||||

|

|||

||||

mofrt.jarxerces.jarctccobol.jartdlang.jar

The recommended way is to include the files in the appropriate CLASSPATHenvironment variable for the utility’s runtime environment before running theprocedure.

If you do not want to change the CLASSPATH environment variable, you canuse the -cp option of the java command in step 5

2. Copy the member DFSMODEL from its distribution library SDFSISRC to thePROCLIB from where your installation submits IMS procedures for batchexecution.

3. Rename the procedure, if desired. This book assumes that you have renamed itDLIMODEL.

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 theDLIModel utility (a Java application). The file is referenced in the PARM field inthe EXEC statement. You need a script file if the command—including the pathand file name of the control data set—exceeds the 100-byte limit. You do notneed a script file if you do not exceed the limit and if you tailor the procedure byplacing the java command directly in the PARM field.

5. If needed, create an HFS script file with the java command. (If you do not needthe script file, use the same syntax as follows for the command in the PARMfield.)

In the HFS script file, write a single-line command using the following syntax:

QQ(1) (2)

java com.ibm.ims.metagen.DLIModel “$1” PDS QT

Notes:

1 The simple form assumes that the java command is accessible throughyour PATH envirnoment variable and that the CLASSPATHenvironment variable includes all necessary .jar files.

2 The $ symbol can vary by locale, so you use the valid value for your USSsetup.

com.ibm.ims.metagen.DLIModelMain class of this DLIModel utility.

″$1″Symbolic parameter that takes the value of the data set name of the utilitycontrol statement data set. This symbolic parameter is set from theDSNAME parameter in the EXEC statement that runs the DLIMODELprocedure.

PDSRequired 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 thefollowing syntax for the command (the single line command has been wrappedto fit the page):

DLIModel Utility Setup


||||

|||

||

|||

||

|

||||||

|||

|

|||||||||||||||

|

|

||||

|||

||

|||||

||

||||

/path/java -cp /path/dlimodel.jar:/path/mofrt.jar:/path/xerces.jar:/path/ctccobol.jar:/path/tdlang.jar com.ibm.ims.metagen.DLIModel "$1" PDS

/path/javaIdentifies 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 containsthe .jar files required by the utility.

Related Reading: For more information about the MVS BPXBATCH utility, seeOS/390: Unix Systems Services User’s Guide and OS/390: Unix SystemsServices Command Reference.

6. If you used a script file, reference the file in the PARM field of the EXECstatement in the DLIMODEL procedure.

As provided, the PARM field references /usr/lpp/ims/imsjava71/dlimodel/go.

Preparing to Run From the MVS USS PromptTo 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 theCLASSPATH environment variable of your shell:

dlimodel.jarmofrt.jarxerces.jarctccobol.jartdlang.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 previoussection.

Alternately, you can add a path prefix to the java command and use the -cp optionof 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 2SDK Standard Edition and Enterprise Edition. IMS Java’s implementation ofJDBC 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 interfaceThe IMS Java hierarchic database interface is more closely related to thestandard DL/I database call interface used with other languages, andprovides a lower-level access to IMS database functions than the JDBCinterface. Using this style of programming, you can build segment searcharguments (SSAs) and call the functions of the DLIConnection object toread, insert, update, or delete segments. With this style, the application hasfull control to navigate the segment hierarchy.

Note: Both styles require that you first describe your IMS databases to the IMSJava 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 basicunderstanding of hierarchical databases.

This chapter uses the sample applications shipped with IMS Java to show how toaccess IMS database. For information on expanding and locating these files, seethe 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 loadthese databases are contained in the directory samples/dealership/databases. Forinformation on how to run the database definition and load jobs, see the IMSsample Readme file in the directory samples/dealership/ims/Readme.

Related Reading: For a full specification of the classes used in this chapter, seethe JavaDoc shipped with IMS Java. If using the default installation directory, theJavaDoc is in directory usr/lpp/ims/imsjava71/docs/.

Introduction to the Example EnvironmentIn this chapter and in Chapter 4, “Writing a Java Application Program” on page 45, asample application program is introduced. The sample program uses an automobiledealership program for illustration purposes. This and other automobile dealershipapplications 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 expandand access these sample applications).

The sample database contains five segment types. The root segment is the Dealersegment. Its child segment is the Model segment. Under the Model segment are itschildren: the segments Order, Stock, and Sales. This is the same databaseexample 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 6on page 25 for the DBD of this database.


|

|

|

|||||

||||||||

|||

||

|||

|||||

|||

||

||||||

|||||||

The Dealer segment identifies a dealer selling cars. The segment contains a uniquedealer number, dealer name and address, and annual sales information.

Dealers carry car types, each of which has a corresponding Model segment. AModel 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 issequenced 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 aparticular order, its serial number and delivery date are added to the segment. Thesegment 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’sinventory. The segment is sequenced by a serial number that is unique to a givenmodel. It contains descriptive information about the car and the date it wasdelivered to the dealer. The segment remains in the database until the car is soldfrom stock.

Finally, when the car is sold, a Sales segment is created. This segment issequenced by sale date and contains information about the car sold and thepurchaser.

JDBC Access Method

Describing Your IMS Databases to IMS JavaProcessing a set of IMS databases by an IMS Java application using JDBCrequires 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 JDBCdatabase 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 DLIModelutility, and specify the generation of the IMS Java metadata class. This is therecommended technique and is described in Chapter 5, “DLIModel Utility” onpage 61.

Figure 4. Example Database Hierarchy


|

|||||

|||

|||||

|||||

|||

||

|

||||

|

||||

v Code the metadata class manually. This is described in Appendix A, “ManuallyCreating IMS Java Metadata Classes” on page 99.

This chapter assumes that you have prepared a metadata class by using theDLIModel utility.

The examples used for the rest of this chapter are based on the following simpleapplication. The PSB for the application is as shown in Figure 5. This database isthe Automobile Dealership database that was introduced in “Introduction to theExample Environment” on page 23.

The physical DBD referenced by this PSB is shown in Figure 6.

The DLIModel utility produces a DLIModel Java Report of its generated metadatastructure. For an example of the report produced by DLIModel see Figure 7 onpage 26.

DLR_PCB1 PCB TYPE=DB,DBDNAME=DEALERDB,PROCOPT=GO,KEYLEN=42SENSEG NAME=DEALER,PARENT=0SENSEG NAME=MODEL,PARENT=DEALERSENSEG NAME=ORDER,PARENT=MODELSENSEG NAME=SALES,PARENT=MODELSENSEG NAME=STOCK,PARENT=MODELPSBGEN PSBNAME=DLR_PSB,MAXQ=200END

Figure 5. Example PSB Definition

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=CFIELD NAME=DLRNAME,BYTES=30,START=5,TYPE=CSEGM NAME=MODEL,PARENT=DEALER,BYTES=43FIELD NAME=(MODTYPE,SEQ,U),BYTES=2,START=1,TYPE=CFIELD NAME=MAKE,BYTES=10,START=3,TYPE=CFIELD NAME=MODEL,BYTES=10,START=13,TYPE=CFIELD NAME=YEAR,BYTES=4,START=23,TYPE=CFIELD NAME=MSRP,BYTES=5,START=27,TYPE=PSEGM NAME=ORDER,PARENT=MODEL,BYTES=127FIELD NAME=(ORDNBR,SEQ,U),BYTES=6,START=1,TYPE=CFIELD NAME=LASTNME,BYTES=25,START=50,TYPE=CFIELD NAME=FIRSTNME,BYTES=25,START=75,TYPE=CSEGM NAME=SALES,PARENT=MODEL,BYTES=113FIELD NAME=(SALDATE,SEQ,U),BYTES=8,START=1,TYPE=CFIELD NAME=LASTNME,BYTES=25,START=9,TYPE=CFIELD NAME=FIRSTNME,BYTES=25,START=34,TYPE=CFIELD NAME=STKVIN,BYTES=20,START=94,TYPE=CSEGM NAME=STOCK,PARENT=MODEL,BYTES=62FIELD NAME=(STKVIN,SEQ,U),BYTES=20,START=1,TYPE=CFIELD NAME=COLOR,BYTES=10,START=37,TYPE=CFIELD NAME=PRICE,BYTES=5,START=47,TYPE=CFIELD NAME=LOT,BYTES=10,START=52,TYPE=CDBDGENFINISHEND

Figure 6. DBD Sample Definition

JDBC Access Method

Chapter 3. Accessing an IMS Database 25

||||||||

|||

|||||||||||||||||||||||||||

|||

||

||

|||||

||

||||

The DLIModel Summary Report provides you with the following information:

v The name of the metadata class (DealerDatabaseView), to use when youestablish 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 theDBD, but also include additional fields specified to DLIModel based (for example)on field layouts of segments in existing applications. For example, the fieldsDealerAddress and YTDSales in the Dealer segment are added fields.

v The names of PCBs, segments, and fields to use in your JDBC calls. Thesenames may be alias names assigned to the IMS entities. Alias names areintended to be more representative and intuitive identifiers for your Java

DLIModel Java Report========================Class: DealerDatabaseView in package: com.ibm.ims.tooling generated for PSB: DLR_PSB

==================================================PCB: DealershipDB==================================================Segment: DEALERField: DealerNumber Type=CHAR Start=1 Length=4 ++ Primary Key Field ++Field: DealerName Type=CHAR Start=5 Length=30Field: DealerAddress Type=CHAR Start=35 Length=50Field: YTDSales Type=PACKEDDECIMAL Type Qualifier=S9(18) Start=85 Length=10==================================================

Segment: MODELField: 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=4Field: EPAHighwayMilage Type=CHAR Start=36 Length=4Field: Horsepower Type=CHAR Start=40 Length=4==================================================

Segment: ORDERField: 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=30Field: Price Type=ZONEDDECIMAL Type Qualifier=99999 Start=37 Length=5Field: OrderDate Type=CHAR Start=42 Length=8Field: SerialNo Type=CHAR Start=100 Length=8Field: DeliverDate Type=CHAR Start=120 Length=8==================================================Segment: SALESField: DateSold Type=CHAR Start=1 Length=8 ++ Primary Key Field ++Field: PurchaserLastName Type=CHAR Start=9 Length=25 (Search Field)Field: PurchasetFirstName Type=CHAR Start=34 Length=25 (Search Field)Field: StockVINumber Type=CHAR Start=94 Length=20 (Search Field)Field: PurchaserAddress Type=CHAR Start=59 Length=25Field: SoldBy Type=CHAR Start=84 Length=10==================================================Segment: STOCKField: StockVINumber Type=CHAR Start=1 Length=20 ++ Primary Key Field ++Field: Color Type=CHAR Start=37 Length=10 (Search Field)Field: Price Type=ZONEDDECIMAL Type Qualifier=99999 Start=47 Length=5Field: Lot Type=CHAR Start=53 Length=10 (Search Field)Field: DateIn Type=CHAR Start=21 Length=8Field: DateOut Type=CHAR Start=29 Length=8

Figure 7. The IMS Java Summary Report

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 fromthe PSB. And a comparison of the names of the segments and the fields in thereport with their names in the DBD shows that they have all been assigned moremeaningful names.

v Data types of fields. The data types of the fields are also based on informationsupplied to the utility, and supplement the simple TYPE property of fields in theDBD. For example, the field YTDSales in Dealer is described as typePACKEDDECIMAL with a Type Qualifier (format descriptor) of S9(18).

v Fields in each segment, identified as primary or secondary index fields, searchfields, or other fields. Generally, predicates in WHERE clauses that are based onindex fields provide the fastest response. However, predicates may be qualifiedon search fields if necessary. Predicates may not be qualified on other fields. Forexample, in segment, Dealer, a search predicate is best qualified onDealerNumber, may be qualified on DealerName if desired, but may not bequalified on DealerAddress or YTDsales.

The report is intended to be a sufficient source of information on your data for youto code JDBC calls and write your application. It should not be necessary for you torefer to the generated metadata class, nor to examine the original PSB and DBDsource 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 DatabaseThis section discusses accessing IMS databases using JDBC.

Classes and Field NamesA database segment definition defines the fields for a set of segment instancessimilar to the way a relational table defines columns for a set of rows in a table. Inthis regard, segments relate to tables, and fields in a segment relate to columns ina table as illustrated in Figure 8 on page 28 Similarly, an instance of a segment in adatabase corresponds to a row (or tuple) in a table. Note that if a segment does nothave a unique key the corresponding relational table should be viewed as having agenerated unique key added to its column (field) list.

JDBC Access Method


|||||

||||

|||||||

||||

||

|

|

|||||||||

For the purpose of writing JDBC calls, a database segment definition defines thefields for a set of segment instances similar to the way a relational table definescolumns for a set of rows in a table. In this way, segments relate to tables, andfields in a segment relate to columns in a table. And so, the name of an IMSsegment from the summary report becomes the table name in an SQL query, andthe 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 tablename in the query:SELECT * FROM Model

In the following example, ModelTypeCode is the name of a field contained in theModel 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 namesassigned by using the DLIModel utility. These names will likely not be the sameeight character names used in the database definition for IMS. Alias names aredescribed in further detail in Chapter 5, “DLIModel Utility” on page 61 and aliasessimply act as references to the eight character names described in the IMS DBD(database definition).

PCB-Qualifying SQL QueriesIn IMS Java Connections are made to PSBs. Therefore, there must be a way tospecify which PCB to use when executing an SQL query on the Connection. To dothis, segments referenced in the FROM clause of an SQL statement should alwaysbe PCB qualified. The one exception to this rule is if the PSB contains only onePCB, in which case the PCB name can be omitted. Here is an example:

Figure 8. IMS DB Segments and Fields with Their Corresponding DB2 Tables and Columns

JDBC Access Method


|

|||||||||

||

|

||

|

||||||

|||||||

Recommendation: For coding clarity and performance reasons, segments in theFROM clause should always be PCB qualified, even when not required (unlessreadability is seriously sacrificed).

Writing an Application that Uses JDBCTo use JDBC to read, update, insert, and delete segment instances, an applicationmust:

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 andexecute it. For an example, see “SELECT” on page 35.

3. Iterate the ResultSet returned from the Statement or PreparedStatement objectto 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 IMSJava 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 importstatement to make IMS database access classes available by their unqualified classnames:import com.ibm.ims.db.*;

Use the following import statement to make JDBC classes available by theirunqualified class names:import java.sql.*;

When using JDBC to access an IMS database, an application programmer providesthe name of the DLIDatabaseView subclass when getting a JDBC Connectionobject.

When the following line from Figure 10 on page 30 is executed, DLIDriver, a class incom.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 JDBCDriverManager determines which of the registered drivers supports the suppliedstring.connection = DriverManager.getConnection("jdbc:dli:dealership.application.DealerDatabaseView");

In this case, because the supplied string begins with jdbc:dli:, JDBC DriverManagerlocates the DLIDriver instance and requests that it create a connection.

SELECT *FROM DealershipDB.Model

Figure 9. PCB-Qualifying SQL Query Example

JDBC Access Method


||

||

|

||||

|

||

|

|||

||

|

|||

||

|||

The following list describes the JDBC 2.1 required interfaces that are implementedin the database package, including limitations in the DL/I implementation of theseinterfaces.

java.sql.Connectionjava.sql.Connection is an object that represents the connection to the

package dealership.application;import com.ibm.ims.base.*;import com.ibm.ims.application.*;import com.ibm.ims.db.*;import java.sql.*;

public class IMSAuto extends IMSApplication {IMSMessageQueue messageQueue = null;InputMessage inputMessage = null;ModelOutput modelOutput = null;Connection connection = null;

public IMSAuto() {super();

}

public static void main(String args[]){IMSAuto imsauto = new IMSAuto();imsauto.begin();

}

public void doBegin() throws IMSException {messageQueue = new IMSMessageQueue();inputMessage = new InputMessage();modelOutput = new ModelOutput();

try {Class.forName("com.ibm.ims.db.DLIDriver");connection = DriverManager.getConnection

("jdbc:dli:dealership.application.DealerDatabaseView");}

catch (Exception e){reply("Connection not established");

}

while(messageQueue.getUniqueMessage(inputMessage)) {if (!inputMessage.getString("ModelTypeCode").trim().equals("")){

if (getModelDetails(inputMessage, modelOutput))messageQueue.insertMessage(modelOutput);

}

else {reply("Invalid Input");

}

IMSTransaction.getTransaction().commit();}

}

public void reply(String errmsg) throws IMSException{ErrorMessage errorMessage = new ErrorMessage();errorMessage.setString("MessageText",errmsg);messageQueue.insertMessage(errorMessage);

}}

Figure 10. JDBC Application

JDBC Access Method


||||||||||||||||||||||||||||||||||||||||||||||||||||||||

||||||

||

database. A Connection reference is retrieved from the DriverManagerobject implemented in the java.sql package. The DriverManager obtains aConnection reference by querying its list of registered Driver instances untilit finds one that supports the universal resource locator (URL) passed toDriverManager.getConnection.

Restriction: IMS does not support the local, connection-based commitscope defined in the JDBC model. Therefore, the DL/I implementation ofConnection.commit, Connection.rollback, and Connection.setAutoCommitresults in an SQLException when called from a client program.

Figure 11 illustrates the code to establish a connection to the database:

java.sql.DatabaseMetaDataDatabaseMetaData defines a set of methods to query information about thedatabase, including capabilities the database might or might not support.The class is provided for tool developers and is normally not used in clientprograms. Much of the functionality is specific to relational databases and isnot implemented for DL/I databases.

java.sql.DriverThe Driver interface itself is not usually used in client programs, althoughan application needs to dynamically load a particular Driver implementationby name. One of the first lines in an IMS JDBC program for DL/I accessmust be:Class.forName("com.ibm.ims.db.DLIDriver");

This code loads the Driver and causes the Driver implementation to registeritself with the DriverManager so that the driver can later be found byDriverManager.getConnection. The Driver implementation creates andreturns a Connection object to the DriverManager. The DL/I implementationof JDBC is not fully JDBC compliant and the Driver member jdbcCompliantreturns false.

java.sql.StatementA Statement interface is returned from Connection.createStatement. TheStatement and its subclass PreparedStatement define the interfaces thataccept SQL statements and return tables as ResultSet objects. The code tocreate 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 throwsan SQLException.

v Aborting a DL/I operation, therefore Statement.cancel throws anSQLException.

v Setting a time-out for DL/I operations, thereforeStatement.setQueryTimeout and Statement.getQueryTimeout throw anSQLException.

connection = DriverManager.getConnection("jdbc:dli:dealership.application.DealerDatabaseView");

Figure 11. Establish a Database Connection

JDBC Access Method


||

|||

|||||

||||

||

||||||

|||||

|

||||||

|||||

|

|

||

||

|||

java.sql.ResultSetThe ResultSet interface defines an iteration mechanism to retrieve the datain rows of a table, and to convert the data from the type defined in thedatabase to the type required in the application. For example,ResultSet.getString converts an integer or decimal data type to an instanceof 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/Iimplementation of ResultSet retrieves a new segment occurrence each timeResultSet.next is called.

Restriction: The DL/I implementation of ResultSet does not support:

v Returning data as an ASCII stream, therefore ResultSet.getAsciiStreamthrows an SQLException.

v Named cursors, therefore ResultSet.getCursorName throws anSQLException.

v The method ResultSet.getUnicodeStream, which is deprecated in JDBC2.0.

java.sql.ResultSetMetaDataThis interface defines methods to provide information about the types andproperties in a ResultSet object. It includes methods such asgetColumnCount, isSigned, getPrecision, and getColumnName.

java.sql.PreparedStatementThe PreparedStatement interface extends the Statement interface, addingsupport for pre-compiling an SQL statement (the SQL statement is providedat construction instead of execution) and for substituting values in the SQLstatement (UPDATE Suppliers SET Status = ? WHERE City = ?).

Supported Data Types in IMS JavaIMS Java supports the following JDBC types. The DLIModel Summary Reportindicates 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 certainJDBC type.

The methods that are marked with “X” are methods designed for accessing thegiven data type. No truncation or data loss occurs using those methods. Themethods that are marked with “O” are all other legal calls; however, data integritycannot 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

ResultSet.getxxxMethods

JDBC TypesT

INY

INT

SM

AL

LIN

T

INT

EG

ER

BIG

INT

FL

OA

T

DO

UB

LE

BIT

CH

AR

VAR

CH

AR

PAC

KE

DD

EC

IMA

L

ZO

NE

DE

CIM

AL

BIN

AR

Y

DA

TE

TIM

E

TIM

ES

TAM

P

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. Allothers are standard SQL types defined in SQL92.

Restriction: PackedDecimal and ZoneDecimal data types do not support the SignLeading or Sign Separate modes. Sign information is always stored with the SignTrailing method.

General Mappings from COBOL Copybook Types to IMS Java and JavaData Types

Table 3 on page 34 describes how COBOL copybook types are mapped toDLITypeInfo 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

PIC 9 BINARY1 (see Table 4)2 (see Table 4)2

COMP-1 FLOAT float

COMP-2 DOUBLE double

PIC 9 COMP-33 PACKEDDECIMAL java.math.BigDecimal

PIC 9 DISPLAY4 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 thenumber of digits in the PICTURE clause. Table 4 describes the type based onPICTURE 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 isassumed to be specified as DISPLAY.

Table 4. DLITypeInfo Constants and Java Types based on PICTURE clause

Digits in PICTURE clause StorageOccupied

DLITypeInfoConstant

Java Type

1 through 4 2 bytes SMALLINT short

5 through 9 4 bytes INTEGER int

10 through 18 8 bytes BIGINT long

Table 5 shows examples of specific CopyBook formats mapped to DLITypeInfoconstants.

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 GrammarThe following SQL keywords are currently supported in IMS Java. All keywords arecase insensitive.

SELECTFROMWHERE

JDBC Access Method


||

|||

|||

|||

|||

|||

|||

||||

|

|

|||

|

||

||

||||||

||||

||||

|||||

||

||

||

||

||

||

||

||

||

||

||

|||

||

|||||

INSERTDELETEUPDATEALLANDDISINCTINTOOR

Restriction: IMS Java does not support aggregate keywords .

SELECTA SELECT statement is a query used as a top-level SQL statement. A SELECTstatement can be executed against a Statement or PreparedStatement object thatreturns the results as a ResultSet object. Figure 12 on page 36 shows sample codethat uses the results of a SELECT query to update modelOutput with the modelinformation. This example requires an inputMessage with the ModelTypeCode.

Notice that the PCB reference name, DealershipDB, qualifies the Model segmentname in the query string.

Segment-Qualifying FieldsSQL 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 queryreferencing the id field must be segment qualified. The following example isincorrect because the id field is not segment qualified:SELECT idFROM PCBName.CHILDWHERE id=’10’

The following example is correct because the id field is segment qualified:SELECT CHILD.idFROM PCBName.CHILDWHERE ROOT.id=’10’

Recommendations:

v For performance reasons, always segment qualify fields (unless readability isseriously sacrificed). A performance improvement is realized since IMS Javadoes not need to search through all the segments to locate the field and checkfor ambiguity.

v It is not necessary to provide the PCB reference name on the query unless thequery is ambiguous without it; however, it is recommended that you alwaysprovide it to remove ambiguity and to remove the need for checking.

SQL Grammar


||||||||

|

|

|||||

||

||||||||

|||

|

|||

|

||||

|||

|

Note: Note the use of trim() in Figure 12. The method trim() is used becauseIMS character fields are padded with blanks if they are not long enough. Ittrims off the extra blanks in the return.

Figure 12 illustrates the use of a Statement object for executing an SQL query. Youcan also use a PreparedStatement object to execute an SQL query. APreparedStatement 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 CarModelFROM DealerDB.ModelWHERE CarYear=’1989’

SELECT Model.CarModelFROM DealerDB.ModelWHERE Model.CarYear=’1989’

public boolean getModelDetails(InputMessage inputMessage,ModelOutput modelOutput) throws IMSException {

// Parse the input message for ModelTypeCodeString queryString = "SELECT * from DealershipDB.Model where ModelTypeCode = "

+ "’" + inputMessage.getString("ModelTypeCode").trim() + "’";// Create a statement and execute it to get a ResultSet

try {Statement statement = connection.createStatement();ResultSet results = statement.executeQuery(queryString);// Send back the result of the query// Note: since "ModelTypeCode" is unique - only 1 row// is returnedif (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

SQL Grammar


||||||||||||||||||||||||||||||||||||||||||

||||||

|||

|

|

|

|||

|||

In IMS Java, you specify only the segment furthest down the hierarchy in the FROMclause. You can query different segments by preceding the field name with thesegment name, as in:SELECT Dealer.DealerName,CarModelFROMDealershipDB.ModelWHERE CarMake=’Ford’

FROMA FROM clause in IMS Java differs from standard SQL in that no explicit joins arerequired nor allowed. Rather, the deepest segment to be accessed should be listedin the FROM clause. This then implies a join of all the segments starting with theone listed in the FROM clause up the hierarchy to the root. For more informationsee “JDBC Access Method” on page 24.

WHEREBy using IMS Java to write IMS applications, you can avoid the long process ofcoding segment search arguments (SSAs) for every segment in the path leading tothe segment being queried. Instead, you can use the IMS Java API for SQL queriesto retrieve results from any segment in the path leading to the segment beingqueried.

The primary difference between SQL queries to relational databases and JDBCqueries to IMS using IMS Java is that the hierarchical structure of an IMS databaseeliminates 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 adealership that sells a particular car model that you are looking for (AnyCarModel):

You must query two independent tables (Dealer and Model) and indicate how theyare joined in the WHERE clause.

In an IMS Java application, you can write the query in Figure 14 to access thesame data in a hierarchical database in a WHERE clause:

In a hierarchical database, all data in segments along the hierarchical path to thetarget segment are implicitly included in the query results and therefore do not needto be explicitly stated. In Figure 14, the information about the Dealer segment isincluded in the result set, because it is along the hierarchical path to the Modelsegment.

SELECT Dealer.AddressFROM Dealer.ModelWHERE Model.CarMake = ’AnyCarModel’

AND Dealer.DealerName = Model.CarrierName

Figure 13. Sample Query

SELECT Dealer.AddressFROM DealershipDB.ModelWHERE Model.CarMake = ’AnyCarModel’

Figure 14. Sample Query

SQL Grammar


||||

||

|||

||

|||

||||

|

|||||

|

|||||

|||

|||

||

|||

|||||

However, in the case of the asterisk operator (*) in a SELECT query, a path call isnot made. In the sample query below, only the fields from the Model segment areretrieved.SELECT *FROM DealershipDB.Model

If fields from more than one segment are desired, they must all be explicitlyrequested in the SELECT clause.

You can use the following operators between field names and values in individualpredicates:

<<===<<!=

You can combine multiple predicates with AND and OR operators. However, youcannot use parentheses and AND always takes precedence over OR.

INSERTAn INSERT statement inserts a segment instance with the specified data under anynumber 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 isspecifically set in the database view. For more information see “Adding DefaultValues for Fields of a Segment” on page 99. Figure 15 shows an example of anINSERT statement that inserts a field in the database:

It is possible to set default values for any field in a segment. For more informationsee “Adding Default Values for Fields of a Segment” on page 99.

A difference between JDBC queries to relational databases and IMS is thatstandard SQL does not have a WHERE clause in an INSERT statement, as tuplesare just being inserted into the table specified after the INTO keyword. In an IMSDL/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 beplaced. In the case of an INSERT statement, the WHERE clause is necessary in allcases 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 thestatement is executed. For example:

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

SQL Grammar


||||||||

|||

|||

||

||

||||||||

||

|

||||||

|

||

|||||||||

INSERT INTO DealerDB.Model(ModelTypeCode, CarMake,CarModel, CarYear, Price, EPACityMileage,EPAHighwayMileage, Horsepower)

VALUES (?,?,?,?,?,?,?,?)WHERE Dealer.DealerNumber=?

DELETEA DELETE statement can delete any number of segment occurrences matching thecriteria specified in the WHERE clause. A DELETE statement with a WHERE clausealso deletes the child segments of the matching segments. If no WHERE clause isspecified, all of the segment occurrences of that type are deleted as are all of itschild segment occurrences. Figure 16 shows an example of a DELETE statement:

UPDATEAn UPDATE statement modifies the value of any number of segment occurrences.

An UPDATE statement applies its SET operation to each instance of a specifiedsegment with matching criteria in the WHERE clause. If the UPDATE statementdoes not have a WHERE clause, the SET operation is applied to all instances ofthe specified segment.

A SET clause contains at least one assignment. In each assignment, the values tothe right of the equal sign are computed and assigned to columns to the left of theequal sign. For example, the UPDATE statement in Figure 17 is called to accept anorder. When a customer accepts an order, the car’s “SerialNo” and delivery datesare filled in:

String updateString = "DELETE from DealershipDB.Order WHERE "+ "Dealer.DealerNumber = ’"+ dealerDesired+ "’ AND "+ "OrderNumber = ’" + orderDesired + "’";

try {Statement statement = connection.createStatement();int results = statement.executeUpdate(updateString);...

}catch (SQLException e) {

...}

Figure 16. Sample DELETE Statement

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 SQLTo improve performance of your IMS Java application, use JDBC preparedstatements for the SQL. The PreparedStatement completes the initial steps inpreparing queries only once so that you only need to provide the parameters beforeeach repeated database call.

The PreparedStatement performs the following only once before repeated databasecalls 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 JDBCAlthough the JDBC interface to an IMS database follows the relational paradigmclosely, remember that the segments are physically stored in a hierarchicaldatabase, which affects the semantics of your JDBC calls to some extent. To avoidunexpected results, or potential performance problems, consider the following:

v When performing a SELECT, generally try to supply predicates in the WHEREclause for all levels down the hierarchy to your target segment.

– If you supply a predicate in the WHERE clause for some target segmentsomewhere down the hierarchy, and omit predicates for its parents, then IMSwill scan all candidate segments at the parent levels in an attempt to matchthe predicate you have supplied. For example, if you are retrieving a secondlevel segment and you supply a a predicate for that second level segment, butdo not supply one for the root segment, then IMS may perform a full databasescan, testing every second-level segment under every root against thepredicate. This has performance implications, particularly at the root level, andmay 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 WHEREclause 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 IMSwill choose the first occurrence of a segment at that level that allows it to satisfyremaining predicates, and perform the insert in that path. This may not be whatyou intended. To take an example of a three-level database, if you insert athird-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 segmentunder the specified root.

v When deleting a segment that is not a bottom-level segment in its hierarchy (inother words, a leaf segment), be aware that you have, in effect, cascadeddeletes down the remaining segments in that hierarchical subtree. The entirefamily of segments of all types that are located hierarchically below your targetdeleted segment will also (generally) be deleted.

v Although not solely related to hierarchies, note that when providing predicates toidentify a segment, the search is generally faster if the predicate is qualified on aprimary or secondary index key field, rather than simply a ″search field″. Primaryand secondary key fields are identified for each segment in the DLIModel JavaReport.

Note: When considering the effects of the database hierarchy on your JDBCoperations, you can find a description of the hierarchy, as it appears in yourapplication view, in the DLIModel Java Report.

SQL Grammar


|

||||

||

|

|

|

|

||||

||

|||||||||

|

||

|||||||

|||||

|||||

|||

IMS Java Hierarchic Database InterfaceEven though you can use the lower-level package to access IMS data, it isrecommended that you use the JDBC package. This package is included forexperienced IMS application developers who need more access than thehigher-level package provides. The IMS Java Hierarchic Database Interfacecontains the following objects and classes:

DLIConnectionA DLIConnection object represents a connection with a set of DL/Idatabases or views (as many PCBs as are in the PSB). It provides theinterface to read, update, insert, and delete segments in a DL/I database.

DLISegmentDLISegment is the class that represents segments in a DL/I database. Itregisters the types of data stored in a segment by providing an array ofDLITypeInfo objects.

Definition: Setter and getter functions use the type information toautomatically locate and convert data in the byte array to the requestedformat. These setter and getter functions can locate data based on both itsoffset in the DLITypeInfo array (fastest) or by using the name of the fieldincluded in the type information.

DLITypeInfoDLITypeInfo, contained in the base package, defines the type, offset, andlength of a field in the byte array of a DLISegment. DLITypeInfo supports allDB2 for OS/390 data types, including packed decimal.

SSA SSA represents a Segment Search Argument. It provides methods to addcommand codes and qualification statements.

SSAListSSAList represents a collection of SSA objects and converts the list to thebyte array necessary to invoke the JavaToDLI methods. The combination ofSSAList, SSA, and SSAQualification statement allows an application tospecify a Segment Search Argument list that fully supports all of itsfeatures.

SSAQualificationStatementAn SSAQualificationStatement represents logical qualification statements toa Segment Search Argument. Qualification statements support both keysearch fields and search fields.

DLIRecordDLIRecord represents the set of segment occurrences from a root segmentdown the hierarchy to the leaf segment. The DLIConnection methodsgetUniqueRecord and getNextRecord update a DLIRecord object using apath call (“D” command code).

DLISegmentInfoDLISegmentInfo is a “wrapper” class that links a DLISegment object to itsparent in the DL/I database hierarchy.

DLIDatabaseViewDLIDatabaseView represents an application’s view of the segments in aDL/I database. It is built as an array of DLISegmentInfo objects, which binda DLISegment object to its parent DLISegment object. DLIDatabaseViewtherefore defines the segment hierarchy. DLIDatabaseView also provides

IMS Java Hierarchic Database Interface


||

|||||

||||

||||

|||||

||||

|||

||||||

||||

|||||

|||

|||||

named lookup of the DLISegment objects. This feature is used by the DL/IJDBC implementation to locate a DLISegment object from the name of asegment used in a query.

Application Programming Using DLIConnectionTo use DLIConnection to read, update, insert, and delete segment instances, yourapplication should:

1. Acquire DLISegment object for each segment using the cloneSegment methodon the subclassed DLIDatabaseView

2. Provide a subclass of DLIDatabaseView that defines the segment hierarchyaccessed 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 deletesegments 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 theDLIModel utility (See Chapter 5, “DLIModel Utility” on page 61). It is recommendedthat you use the DLIModel utility wherever possible.

Creating a DLIConnection ObjectA 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 theDLIDatabaseView object, because it simplifies finding the class by its name.Figure 18 illustrates how to create a DLIConnection object:

Building SSAsSSAs are used to identify the segment to which a DL/I call applies. Due to thehierarchical structure DL/I uses, you often have to specify several levels of SSAs toaccess a segment at a low level in the hierarchy. An SSAList is a collection of oneor more SSAs and the SSAList is what is used in making any DL/I call. TheSSAList is also where you specify which database you want to access within aDLIDatabaseView 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:

DealerDatabaseView dealerView = new DealerDatabaseView();DLIConnection connection = DLIConnection.createInstance(dealerView);

Figure 18. Creating a DLIConnection Object



||

|||

|||

|

||

||

||

|

|

||

||||

|

|

|

|

|||

||

|

||||||

||

|

Accessing DL/I Data using SSAsYou can now issue a database call by invoking the desired access method onDLIConnection passing in:

v the SSAList

v an instance of the segment, that will be the intended target of the database callresults

This passed-in instance should be obtained by calling the cloneSegment method onthe DLIDatabaseView. Finally, the passed-in segment can be examined for theresults of the query.

The following example demonstrates calling and printing-out the results using theSSAList 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);}

// Create an SSAListSSAList modelSSAList = SSAList.createInstance("DealershipDB");

// Construct an unqualified SSA for the Dealer segmentSSA dealerSSA = SSA.createInstance("Dealer");

// Construct a qualified SSA for the Model segmentSSA modelSSA = SSA.createInstance("Model", "CarMake", SSA.EQUALS, "Alpha");// Add an additional qualification statementmodelSSA.addQualification(SSA.AND, "CarYear", SSA.EQUALS, "1989");

// Add the SSAs to the SSAListmodelSSAList.addSSA(dealerSSA);modelSSAList.addSSA(modelSSA);

Figure 19. Creating an SSAList



||||||||||||||

||||||

|

||

|||

||

||||||

|

Chapter 4. Writing a Java Application Program

This chapter uses the sample applications shipped with IMS Java to show how towrite IMS Java applications in different environments. For information on expandingand 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 loadthese databases are contained in the directory samples/dealership/databases. Forinformation on how to run the database definition and load jobs, see the IMSsample 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 ProcessingUsing the IMS Java classes, you can write applications for the following types ofIMS dependent regions:

Java message processing (JMP) regionsJMP regions are similar to MPP regions, but JMP regions only allow thescheduling of Java message-processing programs. A JMP is started whenthere is a message in the queue for the JMP and IMS schedules themessage to be processed. JMP programs are executed through transactioncodes submitted by users at terminals and from other application programs.Each transaction code represents a transaction that the JMP processes. Asingle program can also be started from multiple transaction codes.

JMP programs are very flexible in how they process transactions and wherethey send the output. JMP programs send any output messages back to themessage queues and processes the next message with the sametransaction code. The program continues to run until there are no moremessages with the same transaction code. JMPs share the followingcharacteristics:

v They are small

v They can produce output that is needed immediately

Java batch processing (JBP) regionsJBP regions run flexible programs that perform batch-type processing onlineand can access the IMS message queues for output (similar tonon-message–driven BMPs). JBPs are started by submitting a batch jobwith, for example, JCL or a TSO session. JBPs are like BMPs, except thatthey cannot read input messages from the IMS message queue (forexample: there is no IN= parameter in the startup procedure).

IMS Java applications can run in a DB/DC and DBCTL environments. IMS Javadoes not support batch processing.


|

|

|||

|||||

||||||||

||||||

|

|

|||||||

||

Running Java ApplicationsAfter determining the appropriate type of Java program to use, you must give yourprogram specific instructions from the terminal to run it. You can access programsfrom terminals by providing one of the following types of input:

IMS CommandsStart with slash (/). For example: /START.

Related Reading: See IMS Version 7 Command Reference for moreinformation on IMS commands.

Transaction messageA transaction message is routed to an application program for processing.The program destination is defined by the 1- to 8-byte transaction codeincluded as the first part of the input message.

Message switchA message switch is routed to another terminal. The terminal destination isdefined by the 1- to 8-byte terminal name included as the first part of theinput.

Message QueuingAfter you provide input in one of the forms described above, the message is eitherqueued or sent directly to command process or modules.

Specifically, all full-function database input and output messages are placed inmessage queues, waiting to be enqueued to their destinations or points ofcompletion. However, before getting to the points of completion, IMS messagequeues are held in buffers in main storage until they are either directed to theirdestination or there is a backlog of messages arriving in the queue. If there aremore messages entering the queue than exiting, IMS writes messages to themessage queue data sets until they are directed to their final destinations.

Related Reading: See the IMS Primer for general information on IMS messagequeues.

Reading and Writing Messages to the Message Queue in JavaA basic IMS Java application involves the input and receipt of multiple messagesfrom the message queue, much like applications in other languages. IMS Javaapplications are invoked by transactions; that is, a user at a terminal cancommunicate with the application program and IMS. The actual applications arebuilt with the application package classes using the IMS Java classes and methods.

Building an IMS Java Application by ExampleIn “Introduction to the Example Environment” on page 23, a sample applicationprogram is introduced. The sample program uses an automobile dealershipprogram for illustration purposes. This and other automobile dealership applicationsare available in the samples.tar file shipped with the IMS Java product (See theReadme file in the samples directory for instructions on how to expand and accessthese sample applications).

Related Reading: For a full specification of the classes used in this chapter, seethe JavaDoc shipped with IMS Java. If using the default installation directory, theJavaDoc is in directory usr/lpp/ims/imsjava71/docs/.

Using IMS Java to Build a Message Processing ApplicationTo 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 thesubclass, which is described in “Subclass IMSApplication and Implement main()and doBegin()” on page 48. The doBegin method is an abstract method in thebase class, IMSApplication.

Important: The main method of your subclass must call the begin method ofthe base class, IMSApplication. The begin method of the base class thenperforms initialization and calls the abstract doBegin method that wasimplemented in your subclass.

2. Receive and send IMSFieldMessages.

3. Perform a commit before processing the next message by callingIMSTransaction.getTransaction().commit() by callingIMSTransaction.getTransaction().abend().

Subclass IMSFieldMessage to Define Any Input Messages: Figure 20 gives anexample of subclassing IMSFieldMessage to define an input message that acceptsa two-byte type code of a car model to query a car dealership database foravailable car models.

This example code subclasses IMSFieldMessage to make the fields in the messageavailable to the program and creates an array of DLITypeInfo objects for the fieldsin the message. For the DLITypeInfo, the code identifies first the field name, thenthe data type, the position, and finally the length of the individual fields within thearray. This allows the application to use the access functions withinIMSFieldMessage to automatically convert the data from its format in the messageto a Java type that the application can process. In addition to the message-specificfields it defines, IMSFieldMessage provides access functions that allow it todetermine the transaction code and the length of the message.

Subclass IMSFieldMessage to Define any Output Messages: Figure 21 onpage 48 gives an example of subclassing IMSFieldMessage to define an outputmessage that displays the available car models from a type code query.

This example code creates an array of DLITypeInfo objects and then passes thatarray, the byte array length, and the boolean value false (indicates a non-SPAmessage) to the IMSFieldMessage constructor. For each DLITypeInfo object, youmust first identify the field data type, then the field name, the field offset in the bytearray, and finally the length of the byte array.

package dealership.application;import com.ibm.ims.db.*;import com.ibm.ims.base.*;import com.ibm.ims.application.*;

/* Subclasses IMSFieldMessage to define application’s input messages */public class InputMessage extends IMSFieldMessage {

/* Creates array of DLITypeInfo objects for the fields in message */final static DLITypeInfo[]fieldInfo={

new DLITypeInfo("ModelTypeCode", DLITypeInfo.CHAR, 1, 2)};

public InputMessage() {super(fieldInfo, 2, false);

}}

Figure 20. Subclass IMSFieldMessage: Input Message Sample Code

IMS Applications

Chapter 4. Writing a Java Application Program 47

|||||||||||||||||

|

|||

||||

|||||||||

|||

|||||

Subclass IMSApplication and Implement main() and doBegin(): The examplecode shown in Figure 22 on page 49 demonstrates how to perform the followingactions:

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 moreinformation on the normal flow of this method)

5. Querying the database for a specific model that matches the input model typecode. This method is not implemented yet and is explained more fully inChapter 3, “Accessing an IMS Database” on page 23.

6. Returning detailed information as output about that specific model if it isavailable at the dealership.

7. Returning an error message if the model is not available at the dealership.

package dealership.application;import com.ibm.ims.db.*;import com.ibm.ims.base.*;import com.ibm.ims.application.*;

/*Subclasses IMSFieldMessage to define application’s output messages */public class ModelOutput extends IMSFieldMessage {

/* Creates array of DLITypeInfo objects for the fields in message */final static DLITypeInfo[] fieldInfo={

new DLITypeInfo("Type", DLITypeInfo.CHAR, 1, 2),new DLITypeInfo("Make", DLITypeInfo.CHAR, 3, 10),new DLITypeInfo("Model", DLITypeInfo.CHAR, 13, 10),new DLITypeInfo("Year", DLITypeInfo.DOUBLE, 23, 4),new DLITypeInfo("CityMiles", DLITypeInfo.CHAR, 27, 4),new DLITypeInfo("HighwayMiles", DLITypeInfo.CHAR, 31, 4),new DLITypeInfo("Horsepower", DLITypeInfo.CHAR, 35, 4)

};

public ModelOutput() {super(fieldInfo, 38,false);

}

}

Figure 21. Subclass IMSFieldMessage: Output Message Sample Code

IMS Applications


||||||||||||||||||||||||

|

|||

|

|

|

|||

|||

||

|

Note: IMSMessageQueue.getUniqueMessage returns true if a message was readfrom the queue and false if one was not. Also,IMSTransaction.getTransaction().commit must be called before receivingsubsequent messages from the queue.

Programming Models for IMS Java ApplicationsThe following programming models outline the supported structure for IMSapplications 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 theSSA database access method, database access happens in the same places in theprogram flow as with JDBC.

package dealership.ims;import com.ibm.ims.application.*;

public class IMSAuto extends IMSApplication {�1�IMSMessageQueue messageQueue = null;InputMessage inputMessage = null;ModelOutput modelOutput = null;

public IMSAuto() {super();

}

public static void main(String args[]) {IMSAuto imsauto = new IMSAuto(); �2�imsauto.begin(); �3�

}

public void doBegin() throws IMSException { �4�messageQueue = new IMSMessageQueue();inputMessage = new InputMessage();modelOutput = new ModelOutput();

while(messageQueue.getUniqueMessage(inputMessage)) {if (!inputMessage.getString

("ModelTypeCode").trim().equals("")){if (getModelDetails(inputMessage, modelOutput))�5�

messageQueue.insertMessage(modelOutput); �6�}

else {reply("Invalid Input"); �7�

}

IMSTransaction.getTransaction().commit();

}}

public void reply(String errmsg) throws IMSException{ErrorMessage errorMessage = new ErrorMessage();errorMessage.setString("MessageText",errmsg);messageQueue.insertMessage(errorMessage);

}

}

Figure 22. Subclass IMSApplication Sample Code

IMS Applications


|||||||||||||||||||||||||||||||||||||||||||||

||||

|

||||||

JMP Programming ModelsJMP programs get input messages from the IMS message queue, access IMSdatabases, commit transactions, and can send output messages.

JMP programs are started when IMS receives a message with a transaction codefor the JMP program and schedules the message. JMP programs end when thereare no more messages with that transaction code to process.

JMP Program Without Rollback: Every time the program runs, the programconnects to an IMS database and disconnects when it has processed all of themessages. A transaction begins when the program gets an input message and endswhen the program commits the transaction. Database processing is done only afterthe getUniqueMessage call and before the commit call. The program cannotperform database processing after the commit call and either before the nextgetUniqueMessage 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 connectionreturn;

}

JMP Program using Rollback: A JMP program can roll back databaseprocessing and output messages any number of times during a transaction. Arollback call backs out all database processing and output messages to the mostrecent commit. The transaction must still end with a commit call when the programissues a rollback call, even if there is no further database processing or messagesafter the rollback.public void doBegin() ... { //Application logic runs


repeat {


results=statement.executeQuery(...); //Perform DB processing...MessageQueue.insertMessage(...); //Send output messages...IMSTransaction.rollback(); //Back out of DB processing and

//output messages

results=statement.executeQuery(...); //Perform more DB processing//(optional)

...MessageQueue.insertMessage(...); //Send more output messages

//(optional)...IMSTransaction.commit(); //Commit and end transaction

IMS Applications


|||

|||

|||||||

||||||||||||||||||

||||||

||||||||||||||||||||||

}


}

JMP Program With Per-Transaction Connections: A JMP program needs toopen a database connection only once to process multiple transactions. However, aJMP program can open and close a database connection for each transactionprocessed. The disadvantage is that you add some code complexity and lose asmall amount of performance. But an advantage is it might be easier to port theapplication to other environments where per-transaction connections are required.These per-transaction connections are required if the program uses DB2interoperability to issue any DB2 database calls.public void doBegin() ... { //Application logic runs


repeat {



results=statement.executeQuery(...); //Perform DB processing...MessageQueue.insertMessage(...); //Send output messages...conn.close(); //Close DB connection

IMSTransaction.commit(); //Commit & end transaction}

return;}

JBP Programming ModelsJBP application programs are similar to JMP programs, except that JBP programsdo not receive input messages from the message queue. The program shouldperiodically 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 mustissue a final commit before ending.public void doBegin() ... { //Application logic runs


repeat {

repeat {results=statement.executeQuery(...); //Perform DB processing...MessageQueue.insertMessage(...); //Send output messages...

}

IMSTransaction.commit(); //Periodic commits divide work}

IMS Applications


|||||

||||||||

|||||||||||||||||||||

||||

||||

|||||||||||||||


}

JBP Program using Rollback: Like JMP programs, JBP programs can also backout of database processing and output messages. A final commit call is requiredbefore the program can end, even if no database processing occurs or outputmessages are sent after the last rollback call.public void doBegin() ... { //Application logic runs


repeat {

repeat {

results=statement.executeQuery(...); //Perform DB processing...MessageQueue.insertMessage(...); //Send output messages...IMSTransaction.rollback(); //Back out of DB

//messages

results=statement.executeQuery(...); //Perform more DB//processing (optional)

...MessageQueue.insertMessage(...); //Send more output

//messages (optional)...

}

IMSTransaction.commit(); //Periodic commits divide work}


}

Additional Programming ConsiderationsThis 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 TransactionsA conversational program runs in a JMP region and processes conversationaltransactions that are made up of several steps. It does not process the entiretransaction at the same time. A conversational program divides processing into aconnected series of terminal-to-program-to-terminal interactions. Use conversationalprocessing when one transaction contains several parts.

A non-conversational program receives a message from a terminal, processes therequest, and sends a message back to the terminal. A conversational programreceives a message from a terminal and replies to the terminal, but it saves thedata from the transaction in a scratch pad area (SPA). Then, when the person atthe terminal enters more data, the program has the data it saved from the lastmessage 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 classesenable applications to be built using IMS Java.

Related Reading: For more information on conversational and nonconversationaltransaction processing, see IMS Version 7 Administration Guide: TransactionManager.

Defining a SPA Message: Here are the steps to define a SPA message in aconversational program:

1. Define the SPA message (including the boolean as a SPA parameter). Bydefault, all messages going to (input) and from (output) an IMS Java applicationare transmitted as EBCDIC character data. To use a different type of encoding,you must call the IMSFieldMessage inherited member setDefaultEncoding andprovide the new encoding. This encoding can be any Java supported encoding.In Figure 23, the default encoding is specified as UTF-8.

2. Read the SPA message before reading the application messages:

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

try {// Get the SPA datamsgReceived = 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 receivedoutputMessage.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:

4. End the conversation using the version of insertMessage containing a booleanisLast argument set to true:msgQ.insertMessage(spaMessage, true);

Conversational Transaction Sequence of Events: When the message is aconversational transaction, the following sequence of events occurs:

1. IMS removes the transaction code and places it at the beginning of a messagesegment. The message segment is equal in length to the SPA that was definedfor this transaction during system definition. This is the first segment of the inputmessage that is made available to the program. The second through the nthsegments from the terminal, minus the transaction code, become the remainderof the message that is presented to the application program.

2. When the conversational program has prepared its reply, it inserts the SPA toIMS. The program then inserts the actual text of the reply as segments of anoutput message.

3. IMS saves the SPA and routes the message to the input LTERM (logicalterminal).

4. If the SPA insert specified that another program is to continue the sameconversation, the total reply (including the SPA) is retained on the messagequeue as input to the next program. This program then receives the message ina similar form.

5. A conversational program must be scheduled for each input exchange. Theother processing continues while the operator at the input terminal examines thereply and prepares new input messages.

6. To terminate a conversation, the program places blanks in the transaction codefield of the SPA and inserts the SPA to IMS. In IMS Java this happens when youcall IMSMessageQueue.insertMessage with the boolean parameter isLast set totrue.

7. The conversation can also be terminated if the transaction code in the SPA isreplaced by any non conversational program’s transaction code, and the SPA isinserted to IMS. After the next terminal input, IMS routes that message to theother program’s queue in the normal way.

Handling Multi-Segment MessagesIt 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 inorder to retrieve the entire message. When this occurs, you must provide a

// Set spa data fieldsspaMessage.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

IMS Applications


||||

mapping for each message that is to be read from the queue and use theappropriate methods available from the IMSMessageQueue class.

The following code defines two input messages that comprise a multi-segmentmessage: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 bothmessages://Create a message queueIMSMessageQueue messageQueue = new IMSMessageQueue();//Create the first input messageInputMessage1 input1 = new InputMessage1();//Create the second input messageInputMessage2 input2 = new InputMessage2();

try {//Read the first message from the queuemessageQueue.getUniqueMessage(input1);...//Read the second message from the queuemessageQueue.getNextMessage(input2);...

} catch (IMSException e) {...

}

Coding and Accessing Messages with Repeating StructuresMessages with repeating structures can be defined using a subclass of DLITypeInfocalled DLITypeInfoList. DLITypeInfoList allows you to define an array of repeatingstructures in one object instead of multiple, individual DLITypeInfo objects.DLITypeInfoList is an object that stores an array of DLITypeInfo objects along with acount of its occurrences, thus allowing an input message to contain nestedrepeating 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 manyoccurrences were stored:

IMS Applications


||

||

|||||||||||||||||||||||

||

|||||||||||||||||

|

Note: The creation of the DLITypeInfoList object has no provision for specifying itstype. DLITypeInfoList hard codes the type of the fields toDLITypeInfo.TYPELIST. This design is not constrained to any specific level ofnesting. Within the declaration of model TypeInfo in Figure 26, any of thearray members could be instances of DLITypeInfoList.

To access the nested structures defined in a DLITypeInfoList, use a dotted notationfor specifying the fields and the index of the field within a repeating structure. Thisdotted 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 thefourth “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 samechange to the ModelOutput message:ModelOutput output= new ModelOutput();output.setString("2.4.3", "Red");

Because DLISegment objects are defined using DLITypeInfo objects exactly likeIMSFieldMessages, you can also use these repeating structures within yourdefinitions of DLISegment subclasses. If you do this, however, and you wish to useDLIModel, you will have to modify the generated classes from the utility. DLIModelwill not use DLITypeInfoList definitions in its generated classes. However, youcannot access fields defined in this manner using an SQL query.

Flexible Reading of Multiple Input MessagesThere are times when an application needs to process multiple input messages thatrequire different input data types. For example, the car dealership sampleapplication supports requests to list models, show model details, find cars, cancelorders, and record sales. Each of these requests requires different input data. Thefollowing steps show you how to define the messages to support these requestsand how to access the messages from the application. The letters in the codesamples (for example, �A�) are described on page 58.

1. Define the primary input message. This is the message you pass toIMSMessageQueue.getUniqueMessage to retrieve all of your input messages.Your primary input message must have an I/O area large enough to contain anyof the input requests that your application might receive. It should also containat least one field in common with all your input messages that allows you todetermine the input request. In this example, the common field is

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

IMS Applications


|||||||||||||

||

||||||

“CommandCode,” and the maximum length of each message is 64 (the numberpassed to the IMSFieldMessage constructor):

2. Define separate input messages for each request. Each of these inputmessages contains the same “CommandCode” field as its first field. Each ofthese input messages also uses an IMSFieldMessage constructor that takes anIMSFieldMessage and a DLITypeInfo array. This constructor allows you toremap the contents of the primary input message using the same type ofinformation with each request; therefore, you do not copy the I/O area of themessage, only a reference to this area. Figure 28 on page 58 illustrates codethat created the input messages for the requests “ShowModelDetails,”“FindACar,” and “CancelOrder.”

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

IMS Applications


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 toaccount for the CommandCode’s existence in the byte array. For example, youcan delete the DLITypeInfo entry for “CommandCode” in CancelOrderInput, butthe “OrderNumber” field must still start at offset 21.

v The length of the base class, InputMessage, must be large enough to containany of its subclasses. In this example, InputMessage is 65 bytes because thefields of FindACarInput require it �B�.

v Each InputMessage subclass must provide a constructor to create itself from anInputMessage, as in lines �D�, �F�, and �H�. This constructor uses a newconstructor in IMSFieldMessage, called a copy constructor.

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

IMS Applications


Given this design, an application can provide message reading logic similar toFigure 29.

CICS ApplicationsThe following programming model outlines the supported structure for CICSapplications that use IMS Java. The models are not complete, but show the normalflow of the application for both the JDBC and SSA access methods. This model useJDBC, but for the IMS Java hierarchic database interface method, database accesshappens in the same places in the program flow as with JDBC.public static void main(CommAreaHolder cah) { //Receives control


repeat {results = statement.executeQuery(...); //Perform DB processing...//send output to terminal

}


}

DB2 Stored ProceduresThe following programming model outlines the supported structure for DB2 StoredProcedures that use IMS Java. The models are not complete, but show the normalflow of the application for both the JDBC and SSA access methods. This model useJDBC, but for the IMS Java hierarchic database interface, database accesshappens in the same places in the program flow as with JDBC.public static void targetMethod(...) { //Receives control with

//input or output parameters


repeat {results = statement.executeQuery(...); //Perform DB processing...

}

partmOut[...]=...; //Move results to output//parameters

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

IMS Applications



}

IMS Applications


Chapter 5. DLIModel Utility

This chapter contains information on the DLIModel utility including introductory andpractical 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 OverviewProcessing IMS databases with an IMS Java application requires that you describethe database view of your application’s PSB to IMS Java. You must do this byproviding the name of a metadata class when establishing the JDBC databaseconnection.

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 DLIModelutility, 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 MetadataClasses” 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 COBOLcopybook members.

v Incorporate additional PCB, segment, and field information, or overrides ofexisting information, into the generated class from user-prepared input controlstatements.

v Create a DLIModel Java Report (designed to assist Java applicationprogrammers), 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


|

|

||

|

|

|

|

|

|

|

||

||||

|

||

|

|

||

|

||

||

|||

||

|

||

|

|

|

|

|

|

Figure 30 shows the inputs and outputs of the DLIModel utility. The actions of theutility are directed by control statements that you supply. PSB and DBD sourcemembers are read from their PDS or PDSE data sets and parsed by the utility tobuild an in-memory object model of the database structure and the PSB’s view ofthat 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 memberscorresponding to segments

v Additional field definitions for fields that were not defined in the DBD or COBOLcopybook 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, theutility generates various outputs that were requested through control statements.

Figure 30. The DLIModel Utility Inputs and Outputs

DLIModel Utility Overview


|

||||||||

|

|

|

|

||

||

|

|

||

You can request to have an IMS Java metadata class be generated for each PSBprocessed, together with a corresponding easy-to-read DLIModel Java Report forthe Java programmer to use.

You can request an XMI description of the entire in-memory model (one descriptioncovers 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 necessaryfor problem resolution.

Requirements and Restrictions of the DLIModel Utility

RequirementsThe following are the requirements to run the DLIModel utility.

v PCBs in the PSB must be named, either through statement labels or thePCBNAME parameter.

v If your application uses JDBC and the field list in a call includes fields from morethan one segment in a hierarchic path, then IMS Java employs path calls. In thiscase you must include the PROCOPT=P option in the PCB or SENSEGstatements, 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, inthe usual way.

v This utility will not validate the PSB and DBD source. IBM strongly recommendsthat you generate DBDs, PSBs, and ACBs, correct all errors, and then run theDLIModel utility.

v This utility follows all inter-DBD references when building its model, and mayrequire access to DBDs that are not directly referenced by PCBs in the PSB. Forexample, when processing a PSB that references a main database with anumber of secondary indexes, DLIModel needs access to the secondary indexDBDs even if the PSB does not explicitly name any of these indexes for asecondary processing sequence, or for segment search purposes. Similarly, allDBDs related by logical relationships must be accessible.

v You must maintain the length field in variable length segments on INSERT orUPDATE.

v XMI input files must conform to the COBOL metamodel, which is part of the CAMmetamodel of the OMG-accepted version of the UML specification for theEnterprise Application Integration (EAI) standard.

RestrictionsThe 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 generatedclasses. If you want to define repeating groups of fields in segments (other thanby explicitly defining each group of fields separately) you will have to create theclasses manually or modify the classes generated by DLIModel.


Chapter 5. DLIModel Utility 63

|||

|||

||

||

|

|

||

||||

|||

|||

|||||||

||

|||

|

|

|

|

|

||||

v COBOL copybook XMI files, which supply additional information about fieldlayouts, must describe the physical segments. The files cannot describe thelogical database segment layouts.

Related Reading: For more information about IMS hierarchical databases, seethe:IMS Version 7 Administration Guide: Database Manager and the IMS Version 7Utilities Reference: System.

Output Types of the DLIModel UtilityThis section discusses the different output types of the DLIModel utility.

IMS Java Metadata ClassesThe DLIModel utility produces the necessary metadata classes needed to developIMS Java applications. However, the Java developer needs only to reference theDLIModel Java Report for information about the classes.

Related Reading: For a description of the class source produced, refer to theAppendix A, “Manually Creating IMS Java Metadata Classes” on page 99.

DLIModel Java ReportThe DLIModel Java Report summarizes the structure of the IMS databases in away that allows you to create IMS Java applications and to code SQL queriesagainst the databases. With the DLIModel Report, you do not have to interpret thesyntax 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 fourexamples in “Examples of Using the DLIModel Utility” on page 77.

PSB DescriptionWithin the DLIModel Java Report, a separate section is produced for each PSBnamed in a PSB statement of the control data set. The name of the generated classfor the PSB is given first, which is either the name defined by the JavaNameparameter or, if no JavaName is specified, the 8-character IMS PSB name. Thereport also gives the IMS PSB name and the package for this class, if one wasspecified in the OPTIONS control statement.

PCB DescriptionWithin each PSB, sections are listed for each PCB. Each PCB is identified by itsIMS Java name, which is either the user-chosen JavaName, if one was specified, orthe 8-character IMS PCB name. This is the PCB name that should be used in SQLqueries to the database.

Segment DescriptionWithin each PCB, all segments are listed in hierarchical sequence. Segmentdescriptions are indented to illustrate the hierarchical dependencies. Each segmentis identified by its IMS Java name, which is either the JavaName, if one wasspecified in the control data set, or the 8-character IMS Segment name. Use theIMS Java name for the segment in SQL queries to the database.

Field DescriptionWithin each segment, fields are listed in the order in which they appear in thedatabase DBD with any additional fields appended. Fields are of the followingtypes:



|||

|||

||

|

|

|||

||

|

||||

||

|||||||

|||||

||||||

||||

Field that is physically resident in a DBDA field that is physically resident in a DBD is identified by its IMS Javaname, which is either the user-chosen JavaName, if one was specified, orthe 8-character IMS Field name. This is the name that should be used inSQL queries. A DBD field is further annotated as either a ++ Primary KeyField ++ if it is the sequence field of its segment, or a (Search field) if itis a non-sequence field. SQL queries with WHERE clauses qualified onPrimary Key Fields will generally produce much faster response times thancalls qualified on search fields, but both are allowed.

These fields have their IMS Java type listed, and if necessary, their typequalifier string. They also have their Start position and Bytes listed. It isimportant to note that the Start and Bytes values describe the field’sproperties in the original database segment, not necessarily its Start orBytes as viewed from Java application. The primary purpose of the Startand Bytes values is to describe how these fields overlap or redefine eachother in the database. They are otherwise unnecessary for writing SQLqueries in the Java application.

DBD secondary index search fieldA DBD secondary index search field (a field defined in the DBD with anXDFLD macro) is also identified through its IMS Java name, eitheruser-chosen, or the DBD name. The field is annotated as ++ Secondary KeyField ++, and like a ++Primary Key Field ++ will produce fast responses toqueries. However, secondary index search fields are not physically presentin their segment and can not be retrieved from the Java ResultSet. In thereport, secondary index search fields are followed by a list of theircomponent search fields to assist you in creating a suitable string to use asa search argument in an SQL query.

A secondary index field has no Start or Bytes value in the segment. It isessentially a virtual field and is used for search purposes only.

Field that is not present in the DBDA field that is not present in the DBD is identified (for example, one that hasbeen added by a Field control statement or by an XMI COBOL copybookdescription) 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 nokey field or search field annotation in the report, indicating that it may notbe used in an SQL WHERE clause. However, it may be retrieved from theresult set following successful queries.

XMI Description of the DatabasesAn XMI file, written in UTF-8 encoding, is produced by the utility if you specifygenXMI=YES in the OPTIONS control statement. It describes all of the PSBs andtheir referenced DBDs processed in the entire run of the utility. DBDs shared bymultiple PSBs or PCBs are only described once.

Samples of the XMI produced (converted from UTF-8 to EBCDIC encoding forviewing in an OS/390 environment) for each of the samples in this chapter are inthe 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 thesample 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 databasedefined 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 IMSpackage itself is included and used in the DLIModel utility.

Directory /usr/lpp/ims/imsjava71/samples/dlimodel/model of the distributionmedia contains:

v An EBCDIC-encoded XMI definition of the meta-model to view in an OS/390environment.

v A Rational Rose model file of the meta-model. This model file is at the 4.5/6.0Model level, corresponding to Rose 98 or 98i. To view this file, you need alicensed and installed copy of a suitable level of the Rational Rose product.

DLIModel TraceThe DLI Model utility can generate a trace file, named dlimodeltrace, if you need toresolve a problem with the utility. For the utility to generate the trace file, specifyGenTrace=YES in the OPTIONS statement. You can also specify the path wherethe file is written by using the TracePath parameter.

Control Statements for the DLIModel UtilityYou must write control statements to specify certain options such as input andoutput data set names, and what PSBs and PCBs to use. You can also use thecontrol statements to supply information to the utility about PSBs, PCBs, segments,and fields that cannot be extracted from the PSBs, DBDs, or COBOL copybook XMIfiles.

The control statements are supplied to the utility in a PDS member named in theEXEC statement PARM field of the MVS JCL, or in an HFS file named in acommand line parameter in the MVS USS environment.

Control Data Set RulesYou must include at least the following statements in your control statement dataset:

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 thecontrol data set.

QQ OPTIONS Statement \ \PSB StatementPCB Statement

Q

DLIModel Utility Outputs


||

||

||

|||

|

||||

||

|||||

|||

|

||

|

|

|

|

|

|

|

|

||

||||||||||||||||||||||||||||||||||

||

Q \\ \SEGM Statement

FIELD Statement XDFLD Statement

Q

Q \

INCLUDE StatementQT

If you requested IMS Java metadata class source in the OPTIONS statement, eachPSB that you specified results in a separate metadata .java file, and acorresponding DLIModel Java Report.

A typical reason to include PCB, SEGM, and FIELD statements is to assign tothese entities a customized name (referred to as an alias) that can be used in yourJava program. You can choose a name that is more meaningful than the8-character name given to these entities in the DBD and PSB source. You mightalso need to assign data types to fields, and to define additional fields that areimportant 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 controlstatement 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 controldata set.

v PCB statements must follow immediately after the PSB statement to which theybelong. They may be in any order (for example, PCB statements need not be inthe same order as they appear in the original PSB source).

v FIELD statements must follow immediately after the SEGM for the physicalsegment to which they belong. However, Field statements may be in any orderwithin their segment group. (for example, field statements need not be in thesame sequence as they appear in the original DBD source)

FIELD statements for existing fields and for new fields may be intermixed orgrouped in any sequence.

v INCLUDE statements can be positioned anywhere in a control data set, but notbetween:

– 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. Nestinggives you the flexibility to store your control statements across multiple HFS files orPDS members for increased convenience and control.

For example, a top-level file could contain the OPTIONS, PSB and PCB statementsthat specify a desired Java-class generation. Included files might each contain a

DLIModel Utility Control Statements


||||||||||||||||||||||||||||||||||||||||||||

||||||||||||||||||||

|

|||

||||||

||

|

|

|

||

|

||

|||

||||

||

||

|

|

|||

||

group of SEGM and FIELD statements that relate to an individual logical or physicalDBD. You can reuse these latter files without change for other PSBs that referencethe same databases and segments.

Control Statement RulesThe control statement syntax is very flexible. Each statement consists of anidentifier followed by keyword parameters. The identifier may start in any column.Each identifier, keyword, and variable must be separated by at least onewhitespace character, unless it is already separated by an operator. Keywordparameters can occur in any order.

If your control statements are held in an MVS data set, map the statements tomultiple 80-character records, between columns 1 and 72 inclusive. Columns 73through 80 are ignored, and may be used for sequence numbers if you wish. Nocontinuation characters are required.

If your control statements are held in an HFS file, any line length is acceptable, butyou can optionally continue statements across multiple lines as in MVS. If yourestrict your line length to less than 73 characters, your control statements can bemoved between MVS data sets and HFS files without change.

Identifiers, parameter keywords, and predefined parameter values (such as, YESand 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 StatementOne OPTIONS control statement is required. The statement customizes theDLIModel utility by specifying where to find input, what output to produce, andwhere 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)Package= packagename

Q

QGenJavaSource= NO

GenJavaSource= YES

GenXMI= NO

GenXMI= YES

GenTrace= NO

GenTrace= YES

Q

QOutPath= path JavaSourcePath= path ReportPath= path

Q



|||

|

|||||

||||

||||

|||

|

||||

|

||||||||||||||||

||||||||||||||||||||||||

||||||||||||||||||||||||||||||||||||||||||||||||||||||||

||||||||||||||||||||||||||||||||

||

QXMIPath= path TracePath= path

FieldOrder= DEFAULT

FieldOrder= OFFSET

QT

PSBds=IMS.qual.dsname(member)Required parameter specifies the data set name of the PSB source. If multipleparameters are specified, the utility opens and searches the data sets in theorder of the PDSds parameters when it is reading a PSB. This action is similarto 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 multipleparameters are specified, the utility opens and searches the data sets in theorder of the DBDds parameters when it is reading a DBD. This action is similarto data set concatenation in an MVS JVL DD statement.

Package=packagenameOptional parameter specifies the package that the generated IMS Java classesare for. A Java package statement is added to each .java file produced.

GenJavaSource=YES | NOOptional parameter specifies whether to generate IMS Java class source filesand a DLIModel Java report.

GenXMI=YES | NOOptional parameter specifies whether to generate an XMI file (dlimodelxmi.xmi)that describes the database model based on all PSBs and correspondingdatabases processed by the utility.

GenTrace=YES | NOOptional parameter specifies whether to generate a trace file (nameddlimodeltrace) of the utility run.

OutPath=pathOptional parameter specifies the HFS directory where the utility writes theoutput files, unless you specify path names for specific output files. The defaultis the current directory.

JavaSourcePath=pathOptional parameter specifies the HFS directory where the utility writes the IMSJava class files. Overrides OutPath.

ReportPath=pathOptional parameter specifies the HFS directory where the utility writes theDLIModel Java report. Overrides OutPath.

XMIPath=pathOptional parameter specifies the HFS directory where the utility writes thegenerated XMI. Overrides OutPath.

TracePath=pathOptional parameter specifies the HFS directory where the utility writes the tracefile. Overrides OutPath.

FieldOrder=DEFAULT | OFFSETOptional parameter specifies the order of the fields of segments in thegenerated IMS Java class.



||||||||||||||||||||||||||||||||||||||||

|

|||||

|||||

|||

|||

||||

|||

||||

|||

|||

|||

|||

|||

DEFAULTFields are in the same order as in the DBD and followed by any new fieldsdefined by the control statements.

OFFSETFields are in the order their start positions.

PSB StatementThe 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= namenameprefix* JavaName= name*

QT

PSBName=name | nameprefix | *Required parameter specifies the PSB to be used by the utility.

nameProcess the PSB with the name name.

nameprefix*Process all PSBs with the nameprefix in the specified PSB data set inputfile.

* Process all PSBs in the specified data set input file.

JavaName=nameOptional parameter specifies the name of the generated IMS Java class only ifusing one PSB. Ignored if using nameprefix or ALL for PSBName.

PCB StatementThe PCB statement is optional. It specifies a Java alias for a PCB. All PCBstatements 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=nameRequired parameter specifies the eight-character PCB name that you want toassign an alias to.

JavaName=nameRequired parameter specifies the Java alias for the PCB, which will be used inthe Java application. Must be unique for each PSB.

SEGM StatementThe SEGM control statement is optional and used for physical and logicalsegments.

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 aboutthe 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) andignores any following FIELD statements. Because the utility only issues an error,you can create control statement files that provide information about manysegments and their fields, not all of which are used by the particular PSB beingprocessed.

If an XMI COBOL copybook file was named for a segment, the fields that it definesare 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= nameXMIName= name

QT

DBDName=nameRequired parameter specifies the eight-character DBD name where thesegment is defined.

SegmentName=nameRequired parameter specifies the segment name in the DBD.

JavaName=nameRequired parameter specifies the Java alias for the segment, which will be usedin the Java application. Must be unique for each DBD. If specified, overridesany value that might have been set from a COBOL XMI file.

XMIName=nameOptional parameter specifies the name of an XMI COBOL copybook file thatmay provide additional information about the segment and its existing fields,and definitions of new fields. XMI input is only allowed for physical segments.

FIELD StatementThe FIELD statement is optional. It specifies information about a field or defines anew field for a segment in a physical DBD. All FIELD statements for a segmentmust immediately follow the SEGM statement. However, FIELD statements can bein any order and mixed with XDFLD statements.

When adding information for an existing DBD field, you must specify the 8-characterDBD name of the field using the Name parameter. You can optionally specify thestarting position (Start parameter) and length (Bytes parameter) of the field. If youdo, DLIModel checks these values against the DBD and produces an errormessage if they do not match.

To add information to a non-DBD field that has been inputted from COBOLcopybook XMI file, specify a Java name (JavaName parameter) that matches thename of the copybook field. Do not specify a DBD 8-character field name (Nameparameter). Not specifying a Name parameter, for example, to add a default valueto 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 matchany Java field name in the segment. You must also specify a starting position (Startparameter) and a length (Bytes parameter) for the new field. You can include otherattributes (for example, data type or default value) for the new field.

To define a new field, you must specify the starting position (Start parameter), thelength (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 FIELDName= name Start= int Bytes= name

Q

QJavaName= name JavaType= string TypeQualifier= string

Q

QDefault= string

QT

Name=nameSpecifies eight-character field name as defined in the DBD. Must be uniquewithin segment. Identifies this control statement as applying to an existing fieldwithin the DBD. Do not specify this parameter if you are specifying a new field.

Start=intSpecifies the starting position of the field in the segment. The first byte in thesegment is 1. Required for new fields and optional for existing fields.

Bytes=nameSpecifies the length of the field in the segment. Required for new fields andoptional for existing fields.

JavaName=nameSpecifies the Java alias for the field. Java names of Field statements andXDFLD statements must be unique within a segment. Required if defining anew field and optional for existing fields. If a field has been inputted fromCOBOL copybook XMI file with the same name as the JavaName parameter ona control statement, the control statement is applied to this COBOL copybookfield.

JavaType=stringOptional parameter specifies the Java type of the field. Default is CHAR.Allowed types:

CHARFLOATDOUBLESMALLINTINTEGERBIGINTZONEDDECIMALTIMECARCHARTINYINTBITTYPELISTBINARY



|||||

|||

|

|||||||||||||||||||||||||||||||||

||||||||||||||||||||||||||||||||

|||||||||||||||

|

||||

|||

|||

|||||||

||||||||||||||||

PACKEDDECIMALDATETIMESTAMP

Overrides any value that was set by the XMI COBOL copybook file.

TypeQualifier=stringRequired parameter for some Java types. Specifies type qualifier for thefollowing Java types:

PACKEDDECIMALZONEDDECIMALDATETIMETIMESTAMP

Related Reading: For more information on determining the syntax of typequalifiers, see “Supported Data Types in IMS Java” on page 32.

Default=stringOptional parameter specifies the default value for the field. The default value isused for new instances of the segment when an application does not define avalue for the field. The string must be formatted to match the data type qualifierproperties of the field.

XDFLD StatementThe XDFLD statement is optional. It specifies a Java alias for an existing secondaryindex field in a segment. The DXFLD statements must follow the SEGM statementthat 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 wasdefined in the DBD) by the eight-character name because secondary index fields donot have a starting position in the segment. Secondary index fields do not have adata type. Therefore, you must create a single string that contains the concatenatedsearch fields, each correctly encoded for its data type, when using the index field ina 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=nameRequired parameter specifies the eight-character name of the secondary indexfield as defined in the DBD.

JavaName=nameRequired parameter specifies the Java alias for the field.

INCLUDE StatementThe INCLUDE statement is optional and is only allowed in the top-level controlstatement data set. It specifies a PDS member or HFS file of additional controlstatements to be included in the top-level data set. The included data set must bethe same type (PDS or HFS) as the top-level data set. You are allowed any numberof INCLUDE statements in the top-level data set.

Important: Do not put an INCLUDE statement between PSB statements and PCBstatements or between SEGM statements and FIELD statements. Putting theINCLUDE statement between these statements breaks the required relationshipbetween them.



|||

|

||||||||

||

|||||

||||

||||||

|

||||||||||||||||

|||

||

||||||

||||

The following diagram shows the syntax for the INCLUDE statement.

QQ INCLUDE Dataset= IMS.qual.dsname(member)path/filename

QT

Dataset=IMS.qual.dsname(member) | path/filenameRequired parameter specifies the PDS member of HFS file containing thecontrol statements that are to be included in the top-level data set.

Comment StatementThe Comment Statement is optional. It indicates that a line in the PDS member is acomment 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 UtilityYou can run the DLIModel utility either as a standard OS/390 MVS job, or from thecommand prompt under MVS Unix System Services (USS). For the latteralternative, see “Running the DLIModel Utility From MVS Unix Systems Services”on page 77.

Running the DLIModel Utility as an MVS JobAn MVS procedure is provided in order to run DLIModel as an MVS job. Thisprocedure must initially be moved from its distribution library (where it is named,DFSMODEL) to the procedure library from which your installation executes IMSdatabase utilities. It must be tailored to your installation’s requirements, andoptionally renamed to a name of your choosing. See “DLIModel Utility Setup” onpage 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 onOS/390 using BPXBATCH, an MVS-provided utility that runs any OS/390 UNIXshell command or executable.

The DLIMODEL procedure has two steps:

v Step 1 executes the DLIModel utility (a Java application) by invoking the MVSutility BPXBATCH. The data set name of a PDS control data set is provided tothe utility through the EXEC statement PARM field. This step contains DDstatements for the utility’s standard output steams, STDOUT and STDERR,which are directed to temporary HFS files. Other utility inputs and outputs areread from, or sent to data sets and files with names specified by the control dataset, and do not have DD statements.

v Step 2 redirects STDOUT and STDERR to MVS SYSOUT streams where theycan be viewed using your usual procedures, for example, using SDSF.

The following is the DLIMODEL procedure, which runs the DLIModel utility:



|

|||||||||||||||||

|

|||

|||

|

||

||||

|

|||||||

|||

|

|||||||

||

||

PROC Statement ParametersDSNAME

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 ParametersPGM=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 HFSscript file.

DSNAME is a string parameter containing the fully qualified data set name ofthe top-level control data set, which contains the DLIModel utility controlstatements (as described in section “Control Statements for the DLIModelUtility” on page 66). DSNAME must refer to an MVS partitioned data setmember. The format is:qual1.qual2.dsname(member)

The named data set should be F or FB type with an LRECL=80.

Step 1 DD StatementsSTDENV DD

Contains statements that set the Java environment variables. You shouldnot need to use this DD statement.

STDOUT DDThe destination to which the utility in STEP 1 directs standard output. Thisincludes messages recording the normal execution of the utility. This outputis redirected by STEP 2 to the standard MVS SYSOUT destination.

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

Running the DLIModel Utility


|||||||||||||||||||||||

||||

|

||

||

|

||

||

||

|||||

|

|

|

|||

||||

STDERR DDThe destination to which the utility in STEP 1 directs standard error output.This includes error and warning messages related to the execution of theutility. This output is redirected by STEP 2 to the standard MVS SYSOUTdestination.

SYSTSIN DDProvides control cards for the MVS utility IKJEFT01 to copy the temporaryHFS output files to the MVS SYSOUT destination.

Step 2 EXEC Statement ParametersPGM=IKJEFT01

Runs the MVS utility IKJEFT01, which redirects STDOUT and STDERR to MVSSYSOUT.

DYNAMNBRSee OS/390: Unix Systems Services User’s Guide and OS/390: Unix SystemsServices Command Reference.

CONDSee OS/390: Unix Systems Services User’s Guide and OS/390: Unix SystemsServices Command Reference.

Step 2 DD StatementsSYSTEPRT DD

IKJEFT01 utility output.

HFSOUT DDInput from the temporary STDOUT file from step 1.

HFSERR DDInput from the temporary STDERR file from step 1.

STDOUTL DDOutput destination for the STDOUT stream.

STDERRL DDOutput destination for the STDERR stream.

SYSPRINT DDIKEJEFT01 utility output.

SYSTSIN DDMust be added to execution JCL. Provides control statement input for theIKJEFT01 utility that redirect HFSOUT and HFSERR streams to the STDOULand 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 thisscript 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, itspreparation is a one-time task. Once prepared it will be effectively invisible to userssubmitting the utility to MVS from ISPF.

Related Reading: For more information about the MVS BPXBATCH utility, seeOS/390: Unix Systems Services User’s Guide and OS/390: Unix Systems ServicesCommand 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 *OCOPY INDD(HFSOUT) OUTDD(STDOUTL)OCOPY INDD(HFSERR) OUTDD(STDERRL)/*

In this example, the IKJEFT01 SYSTSIN DD statement is provided with controlcards to copy the temporary HFS outputs to MVS SYSOUT destinations.

Running the DLIModel Utility From MVS Unix Systems ServicesIn addition to the JCL PROC, you can run the DLIModel utility from a prompt underMVS Unix System Services (USS). You can use this method if you are morefamiliar with a Unix environment than with MVS JCL or ISPF. See “DLIModel UtilitySetup” on page 19 for recommendations on adjusting your shop’s Java environmentfor 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

javaRuns JDK 1.3.1 java command

com.ibm.ims.metagen.DLIModelMain class of the DLIModel utility

path/ControlFileHFS file for control data set

Examples of Using the DLIModel UtilityThe section shows examples of how the DLIModel utility uses DBDs, PSBs, controlstatements, and JCL to create IMS Java classes and DLIModel Java reports.

The examples in this section are in the following directories:/usr/lpp/ims/imsjava71/samples/dlimodel/example1//usr/lpp/ims/imsjava71/samples/dlimodel/example2//usr/lpp/ims/imsjava71/samples/dlimodel/example3//usr/lpp/ims/imsjava71/samples/dlimodel/example4/

Example 1. Simple ExampleFigure 32 on page 78 shows a DBD for a single physical database with twosegments. It is referenced by the PSB, with a single PCB and two sensitivesegments shown in Figure 33 on page 78.



|

||||||||

||

|

|||||

|

||||||||||||

||

||

||

||

||

|

||||

|

||||

Note that the PCB is given a name, as required by IMS Java. In this case a label isused, but a PCBNAME= parameter is also acceptable.

A simple MVS JCL execution of the DLIModel utility, using this PSB and DBD, isshown in Figure 34.

The control data set, DSNAME=IMSVS.TEST1.JCL(EXAMPLE1) is shown inFigure 35.

The utility processes a single PSB named AUTPSB1 and its DBD, DEALDB1. Theutility reads the PSB and DBD from data sets IMSVS.TEST1.PSBSRC andIMSVS.TEST1.DBDSRC. It generates an IMS Java class only for this PSB, sinceno other output is requested. The name of the generated class isAUTPSB1DatabaseView (the first 7 characters of this name are set from the PSBname) and the class is written to the HFS file, AUTPSB1DatabaseView.java under thecurrent directory. STDOUT is redirected to SYSOUT, but (in the absence of errors)

DBD NAME=DEALDB1,ACCESS=(HDAM,OSAM), XRMNAME=(DFSHDC40,1,5,200)

DATASET DD1=DFSDLRSEGM NAME=DEALER,PARENT=0,BYTES=61FIELD NAME=(DLRNO,SEQ,U),BYTES=4,START=1,TYPE=CFIELD NAME=DLRNAME,BYTES=30,START=5,TYPE=CSEGM NAME=MODEL,PARENT=DEALER,BYTES=37FIELD NAME=(MAKE,SEQ,U),BYTES=10,START=1,TYPE=CFIELD NAME=MODEL,BYTES=10,START=11,TYPE=CDBDGENFINISHEND

Figure 32. Physical DBD for Simple Example

PCB1 PCB TYPE=DB,DBDNAME=DEALDB1,PROCOPT=A,KEYLEN=28SENSEG NAME=DEALER,PARENT=0SENSEG NAME=MODEL,PARENT=DEALERPSBGEN PSBNAME=AUTPSB1,LANG=ASSEM,CMPAT=YESEND

Figure 33. PSB for Simple Example

//BPXAUTP6 JOB CLASS=Z,MSGCLASS=E,MSGLEVEL=(1,1)//TEST EXEC DLIMODEL// DSNAME="DSNAME=IMSVS.TEST1.JCL(EXAMPLE1)"//STEP2.SYSTSIN DD *OCOPY INDD(HFSOUT) OUTDD(STDOUTL)OCOPY INDD(HFSERR) OUTDD(STDERRL)/*

Figure 34. Minimal MVS JCL stream

Options GenJavaSource=yesPSBds=IMSVS.TEST1.PSBSRCDBDds=IMSVS.TEST1.DBDSRC

PSB PSBName=AUTPSB1

Figure 35. Control Data Set for Simple Example

DLIModel Utility Examples


||||||||||||

|||

|||||

|||

|||||||

|||

||||

|||

|

||

|||

|||

|||||||

consists of only startup and normal completion messages. The DLIModel JavaReport (produced whenever IMS Java classes are generated) is written to the HFSfile, AUTPSB1JavaReport.txt.

The DLIModel Java Report, shown in Figure 36, describes the generated IMS Javametadata class AUTPSB1DatabaseView.

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 IMSPSB and DBD source members. These are the defaults that are used when nocontrol statements or XMI COBOL copybook files are supplied to specify moredeveloper-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 copybookfiles 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 searchfield. 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 theWHERE clause of a JDBC statement, but Primary Key Fields generally provide amuch faster response. In the example, these are the only field types, since thereare no control statements or XMI COBOL copybook files to add additional fields,and no secondary indexes.

Example 2. Example With a Logical RelationshipFigure 37 on page 80 and Figure 38 on page 80 show two physical DBDs linked bya bidirectional logical relationship.

DLIModel Java Report========================Class: AUTPSB1DatabaseView generated for PSB: AUTPSB1

==================================================PCB: PCB1==================================================Segment: DEALERField: DLRNO Type=CHAR Start=1 Length=4 ++ Primary Key Field ++Field: DLRNAME Type=CHAR Start=5 Length=30 (Search Field)==================================================

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



|||||||||||||||

|||

|||

|||

|

|

|

|

|

||||

|||

|||||||

|

|||

In these two physical DBDs, note that segment, EMPL in EMPDB2 is a logicalparent, and it is pointed to by physical logical child, SALESPER in DEALDB2. The

DBD NAME=EMPDB2,ACCESS=(HDAM,OSAM), XRMNAME=(DFSHDC40,1,5,200)

DATASET DD1=DFSEMPLSEGM NAME=EMPL,PARENT=0,BYTES=56LCHILD NAME=(SALESPER,DEALDB2),PAIR=EMPSAL,POINTER=DBLEFIELD NAME=(EMPNO,SEQ,U),BYTES=6,START=1,TYPE=CFIELD NAME=LASTNME,BYTES=25,START=7,TYPE=CFIELD NAME=FIRSTNME,BYTES=25,START=32,TYPE=CSEGM 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=61FIELD NAME=(STATE,SEQ,M),BYTES=2,START=51,TYPE=CFIELD NAME=ADDRESS,BYTES=61,START=1,TYPE=CFIELD NAME=STREET,BYTES=25,START=1,TYPE=CFIELD NAME=CITY,BYTES=25,START=26,TYPE=CDBDGENFINISHEND

Figure 37. EMPDB2 Physical DBD for Logical Relationship Example

DBD NAME=DEALDB2,ACCESS=(HDAM,OSAM), XRMNAME=(DFSHDC40,1,5,200)

DATASET DD1=DFSDLRSEGM NAME=DEALER,PARENT=0,BYTES=61FIELD NAME=(DLRNO,SEQ,U),BYTES=4,START=1,TYPE=CFIELD NAME=DLRNAME,BYTES=30,START=5,TYPE=CFIELD NAME=CITY,BYTES=10,START=35,TYPE=CSEGM NAME=MODEL,PARENT=DEALER,BYTES=37FIELD NAME=(MODKEY,SEQ,U),BYTES=24,START=3, X

TYPE=CFIELD NAME=MODTYPE,BYTES=2,START=1,TYPE=CFIELD NAME=MAKE,BYTES=10,START=3,TYPE=CFIELD NAME=MODEL,BYTES=10,START=13,TYPE=CFIELD NAME=YEAR,BYTES=4,START=23,TYPE=CFIELD NAME=MSRP,BYTES=5,START=27,TYPE=PSEGM NAME=ORDER,PARENT=MODEL,BYTES=74FIELD NAME=(ORDNBR,SEQ,U),BYTES=6,START=1,TYPE=CFIELD NAME=LASTNME,BYTES=25,START=7,TYPE=CFIELD NAME=FIRSTNME,BYTES=25,START=32,TYPE=CFIELD NAME=DATE,BYTES=10,START=57,TYPE=CLCHILD NAME=(SINDXA,SINDEX2),POINTER=INDXXDFLD NAME=XFLD2,SRCH=(LASTNME,FIRSTNME,ORDNBR), X

DDATA=DATESEGM NAME=SALESPER,PARENT=((DEALER,),(EMPL,PHYSICAL,EMPDB2)),X

BYTES=6, XPOINTER=(LPARNT,LTWINBWD,TWINBWD), XRULES=(VVV)

FIELD NAME=(EMPNO,SEQ,U),BYTES=6,START=1,TYPE=C (LPK)SEGM NAME=SALESINF,PARENT=SALESPER,BYTES=15FIELD NAME=QUOTA,BYTES=5,START=1,TYPE=CFIELD NAME=SALESYTD,BYTES=5,START=6,TYPE=CFIELD NAME=COMSSION,BYTES=5,START=11,TYPE=CDBDGENFINISHEND

Figure 38. DEALDB2 Physical DBD for Logical Relationship Example



||||||||||||||||||||

|||

|||||||||||||||||||||||||||||||||||

|||

|

||

relationship is bidirectional with virtual pairing, and the sequence of the logical childchain is defined through the key field, DLRNO2 in the virtual logical child, EMPSALin EMPDB2 -- that is actually the destination parent concatenated key fromDEALER in DEALDB2.

Figure 39 shows a logical DBD based on these two physical DBDs. The logicalDBD is rooted in the EMPDB2 physical DBD, and crosses the logical relationship tothe DEALDB2 DBD via EMPSAL and DEALER to include the SALESINF segmentfrom the DEALDB2 database. The EMPSAL and DEALER segments form aconcatenated segment, with data from both physical segments present in the I/Oarea.

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 twoof the three fields in that segment are visible. Also, in this example, the field lengthsand start positions are specified so that there is an empty single byte between thetwo fields.

The JCL stream to execute the utility is similar to that presented in Figure 34 onpage 78 of the previous Example 1.

The minimal control data set presented in Example 1 could also work for thisexample. However, the control data set IMSVS.TEST1.JCL(EXAMPLE2) shown inFigure 41 on page 82 makes use of a few more control statements for purposes ofillustration.

DBD NAME=EMPLDB2,ACCESS=LOGICALDATASET LOGICALSEGM 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))DBDGENFINISHEND

Figure 39. Logical DBD for Logical Relationship Example

PCB1 PCB TYPE=DB,DBDNAME=EMPLDB2,PROCOPT=A,KEYLEN=14SENSEG NAME=EMPL,PARENT=0SENSEG NAME=DEALER,PARENT=EMPLSENSEG NAME=SALESINF,PARENT=DEALERSENFLD NAME=QUOTA,START=1SENFLD NAME=SALESYTD,START=7SENSEG NAME=EMPLINFO,PARENT=EMPLPSBGEN PSBNAME=AUTPSB2,LANG=ASSEM,CMPAT=YESEND

Figure 40. PSB with Field-Level Sensitivity for Logical Relationship Example



||||||||||||

|||

|||||||||

|||

||||

|||||||

||||||

||

|||||

The utility processes AUTPSB2, and the DBDs, DEALDB2 and EMPDB2. Asalready discussed, it reads the PSB and DBD from data sets,IMSVS.TEST1.PSBSRC and IMSVS.TEST1.DBDSRC. The JavaName parameter inthe PSB statement sets the name of the generated class, and also determines thenames of some of other output files. The utility generates an IMS Java classnamed, EmployeeView, and writes it to the HFS file, EmployeeView.java. A packagestatement is included in the class source to specify that the class is part of thepackage, example2.

An XMI stream describing the data view of AUTPSB5 and its databases isgenerated and written to the file, xmiOutput.xmi. A trace of the execution is writtento the file, dlimodeltrace. The DLIModel Java Report is written to the file,EmployeeViewJavaReport.txt. Since no paths are specified for these outputs, theyare all written to the default directory in the HFS file system.

Figure 42 shows the DLIModel Java Report from this execution. It matches thegenerated IMS Java metadata class (not shown).

There are three significant differences in this report as opposed to the precedingsimple report shown in Figure 36 on page 79.

v First, note that the layout of the DEALER segment reflects the fact that it is aconcatenated segment. The first field, DLRNO2, is the destination parent

Options PSBds=IMSVS.TEST1.PSBSRCDBDds=IMSVS.TEST1.DBDSRCGenJavaSource=yes Package=example2GenXMI=yes GenTrace=yes

PSB PSBName=AUTPSB2 JavaName=EmployeeView

Figure 41. Control Data Set for Logical Relationship Example

DLIModel Java Report========================Class: EmployeeView in package: example2 generated for PSB: AUTPSB2

==================================================PCB: PCB1==================================================Segment: EMPLField: 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: DEALERField: DLRNO2 Type=CHAR Start=1 Length=4 ++ Primary Key Field ++Field: DLRNO Type=CHAR Start=11 Length=4 (Search Field)Field: DLRNAME Type=CHAR Start=15 Length=30 (Search Field)Field: CITY Type=CHAR Start=45 Length=10 (Search Field)==================================================

Segment: SALESINFField: QUOTA Type=CHAR Start=1 Length=5 (Search Field)Field: SALESYTD Type=CHAR Start=7 Length=5 (Search Field)

==================================================Segment: EMPLINFOField: STATE Type=CHAR Start=51 Length=2 ++ Primary Key Field ++Field: ADDRESS Type=CHAR Start=1 Length=61 (Search Field)Field: STREET Type=CHAR Start=1 Length=25 (Search Field)Field: CITY Type=CHAR Start=26 Length=25 (Search Field)

Figure 42. DLIModel Java Report for Logical Relationship Example



|||||

|||

|||||||||||||||||||||||||||

|||

||||||||

|||||

|||

||

||

concatenated key associated with the virtual logical child, EMPSAL. Since thelogical relationship is being crossed by way of this virtual logical child, its SEQfield, DLRNO2, becomes the key field of the concatenated segment. There areno other fields in the EMPSAL segment, but if there had been, they would havefollowed the DLRNO2 field in the report. The fields DLRNO, DLRNAME andCITY, are all fields from the destination parent, DEALER, in DEALDB2.

v Second, note that the SALESINF segment has two fields, QUOTA andSALEYTD, reflecting the sensitive fields defined in the PSB. Neither is a keyfield, since the SALESINF segment does not have a defined sequence field inthe DBD.

v Finally, the EMPLINFO segment illustrates field redefinition in the DBD. Thesegment primary key field, STATE, appears first, as it does in the DBD. Thesecond field listed, ADDRESS, redefines STREET and CITY, and the key field,STATE. This is indicated by the lengths and starting positions of the fields. IMSJava, the generated metadata class, and the report accommodate anyredefinitions present in the FIELD definitions of the IMS DBD.

Example 3. Example With a Secondary IndexExample 3 uses the same physical DBDs as Example 2.

Note that the segment ORDER in DEALDB2 has an XDFLD statement that definesa secondary index search field, XDFLD2, and that it has an LCHILD statement thatreferences the secondary index database, SINDEX2 (as shown in the followingfragment).

LCHILD NAME=(SINDXA,SINDEX2),POINTER=INDXXDFLD NAME=XFLD2,SRCH=(LASTNME,FIRSTNME,ORDNBR), X

DDATA=DATE

The SRCH fields and the DDATA field named in the XDFLD statement all refer tofields in the ORDER segment itself, so in this example the source segment is thesame as the target segment. However, this is not required by IMS Java.

The corresponding secondary index database is shown in Figure 43.

The logical database used by this example, Figure 44 on page 84 is based onDEALDB2, and does not cross any logical relationships.

DBD NAME=SINDEX2,ACCESS=(INDEX,VSAM)DATASET DD1=SINDX2PSEGM NAME=SINDXA,PARENT=0,BYTES=66FIELD NAME=(XFLDA,SEQ,U),BYTES=56,START=1,TYPE=C SEARCHFIELD NAME=DATE,BYTES=10,START=57,TYPE=C DUP DATALCHILD NAME=(ORDER,DEALDB2),INDEX=XFLD2DBDGENFINISHEND

Figure 43. DBD for Secondary Index Example



|||||||||

|||

||||||

||||

||||||

|

|

||||

|||

|||

||

|||

The PSB is shown in Figure 45. The PROCSEQ= parameter in the PCB macrospecifies a secondary processing sequence using the SINDEX2 secondary index.

This example is intended to be run from the USS prompt, instead of via JCL, as theprevious examples were. A hypothetical command line is shown in Figure 46.

The control file, ./ctlfiles/ctl1 is shown in Figure 47.

In this control data set, a PCB control statement overrides the label in the IMS PCBstatement (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).

DBD NAME=DEALLDB2,ACCESS=LOGICALDATASET LOGICALSEGM NAME=DEALER,PARENT=0,SOURCE=((DEALER,,DEALDB2))SEGM NAME=MODEL,PARENT=DEALER,SOURCE=((MODEL,,DEALDB2))SEGM NAME=ORDER,PARENT=MODEL,SOURCE=((ORDER,,DEALDB2))DBDGENFINISHEND

Figure 44. Logical DBD for Secondary Index Example

PCB1 PCB TYPE=DB,DBDNAME=DEALLDB2,PROCOPT=GR,KEYLEN=100, XPROCSEQ=SINDEX2

SENSEG NAME=ORDER,PARENT=0SENSEG NAME=MODEL,PARENT=ORDERSENSEG NAME=DEALER,PARENT=MODELPSBGEN PSBNAME=AUTPSB3,LANG=ASSEM,CMPAT=YESEND

Figure 45. PSB for Secondary Index Example

> java com.ibm.ims.metagen.dlimodel ./ctlfiles/ctl1

Figure 46. MVS USS Command for Secondary Index Example

Options PSBds=IMSVS.TEST1.PSBSRCDBDds=IMSVS.TEST1.DBDSRCGenJavaSource=yes Package=example3GenXMI=yes GenTrace=yes

PSB PSBName=AUTPSB3 JavaName=OrderViewPCB PCBName=PCB1 JavaName=OrdersByName

Figure 47. Control Data Set for Secondary Index Example



||||||||

|||

|||||||

|||

|

|||

||||||

|||

|||

|||

||

||

|||

The difference between this Java Report and preceding examples is the presenceof the secondary index in the ORDER segment. Note that the ORDER segment nolonger 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 JDBCcall 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 theapplication.

In this example, where source and target segments are the same, the componentsearch fields are also present in the ORDER segment, and so they could beretrieved as individual fields. In general, however, these fields may not be defined inthe target segment, and so it would not be possible to retrieve them as individualfields.

Note also that the component search fields of the secondary index field are listed inthe report under the index field description. This information is intended to help theapplication developer construct suitable search strings for WHERE clauses that usethe index field. In this example, since the source and target segments are thesame, 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 StatementsThis example uses the physical database and PSB shown in Figure 49 on page 86and Figure 50 on page 86 to illustrate the use of control statements to defineadditional fields and additional name and data type information. It is the sameexample that is used in Chapter 3, “Accessing an IMS Database” on page 23 to

DLIModel Java Report========================Class: OrderView in package: example3 generated for PSB: AUTPSB3

==================================================PCB: OrdersByName==================================================Segment: ORDERField: 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=CHARFIRSTNME. Length=25. Type=CHARORDNBR. Length=6. Type=CHAR

==================================================Segment: MODELField: 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: DEALERField: DLRNO Type=CHAR Start=1 Length=4 ++ Primary Key FieldField: DLRNAME Type=CHAR Start=5 Length=30 (Search Field)Field: CITY Type=CHAR Start=35 Length=10 (Search Field)

Figure 48. DLIModel Java Report for Secondary Index Example



||||||||||||||||||||||||||||||

||||||||||

|||||

|||||||

|

||||

describe how to access IMS databases from Java applications using JDBC. Thisexample also illustrates how control statements might be split across more than onefile.

The example is executed from the MVS USS prompt, as shown in Figure 51.

The top-level control statement file, ctl4, is shown in Figure 52 on page 87.

DBD NAME=DEALERDB,ACCESS=(HDAM,OSAM),RMNAME=(DFSHDC40.1.10)SEGM NAME=DEALER,PARENT=0,BYTES=94FIELD NAME=(DLRNO,SEQ,U),BYTES=4,START=1,TYPE=CFIELD NAME=DLRNAME,BYTES=30,START=5,TYPE=CSEGM NAME=MODEL,PARENT=DEALER,BYTES=43FIELD NAME=(MODTYPE,SEQ,U),BYTES=2,START=1,TYPE=CFIELD NAME=MAKE,BYTES=10,START=3,TYPE=CFIELD NAME=MODEL,BYTES=10,START=13,TYPE=CFIELD NAME=YEAR,BYTES=4,START=23,TYPE=CFIELD NAME=MSRP,BYTES=5,START=27,TYPE=PSEGM NAME=ORDER,PARENT=MODEL,BYTES=127FIELD NAME=(ORDNBR,SEQ,U),BYTES=6,START=1,TYPE=CFIELD NAME=LASTNME,BYTES=25,START=50,TYPE=CFIELD NAME=FIRSTNME,BYTES=25,START=75,TYPE=CSEGM NAME=SALES,PARENT=MODEL,BYTES=113FIELD NAME=(SALDATE,SEQ,U),BYTES=8,START=1,TYPE=CFIELD NAME=LASTNME,BYTES=25,START=9,TYPE=CFIELD NAME=FIRSTNME,BYTES=25,START=34,TYPE=CFIELD NAME=STKVIN,BYTES=20,START=94,TYPE=CSEGM NAME=STOCK,PARENT=MODEL,BYTES=62FIELD NAME=(STKVIN,SEQ,U),BYTES=20,START=1,TYPE=CFIELD NAME=COLOR,BYTES=10,START=37,TYPE=CFIELD NAME=PRICE,BYTES=5,START=47,TYPE=CFIELD NAME=LOT,BYTES=10,START=53,TYPE=CDBDGENFINISHEND

Figure 49. Physical DBD for Multiple Control Statements Example

DLR_PCB1 PCB TYPE=DB,DBDNAME=DEALERDB,PROCOPT=GO,KEYLEN=42SENSEG NAME=DEALER,PARENT=0SENSEG NAME=MODEL,PARENT=DEALERSENSEG NAME=ORDER,PARENT=MODELSENSEG NAME=SALES,PARENT=MODELSENSEG NAME=STOCK,PARENT=MODELPSBGEN PSBNAME=DLR_PSB,MAXQ=200END

Figure 50. PSB for Multiple Control Statements Example

> java com.ibm.ims.metagen.dlimodel ./ctlfiles/ctl4

Figure 51. MVS USS Command for 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 specifieddirectory (outpath=gen). It also names the PSB to be processed, assigns a Javaname for the generated class for this PSB, and provides a Java name for a PCB inthat PSB.

Unlike previous examples, this example includes a second-level control statementfile, called cntrstmt2, which is shown in Figure 53 on page 88. This control fileprovides details of additional fields in the segments of the database referenced fromDLR_PCB1, and additional information about existing fields in that database. Notetwo facts about this second control statement file:

v The information it contains is only necessary because there are additional factsabout the segments in this database that are needed by this (hypothetical) Javaapplication. 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 canuse the standard 8-character names, then you would not need to supply SEGMor Field control statements.

v The Segment and Field control statements need only be split off into a secondfile if it is convenient to do so, perhaps because this additional segmentinformation needs to be shared by other applications. In such cases you mightgroup all field information for a whole database (as is shown in Figure 53 onpage 88) or for each segment into its own file. If this is not advantageous for yourdata, it is equally acceptable to place all control statements in a single, top-levelfile.

OPTIONSPSBds=IMSVS.TEST1.PSBSRC DBDds=IMSVS.TEST1.DBDSRCGenJavaSource=YESgentrace=yesoutpath=genPackage=com.ibm.ims.tooling

PSB psbName=DLR_PSB JavaName=DealerDatabaseViewPCB PCBName=DLR_PCB1 JavaName=DealershipDBInclude Dataset=tests.samp.ctl/cntrstmt2

Figure 52. Top-Level Control Data Set for Multiple Control Statements Example



||||||||||

||||||||

|||||

||||||

|||||||

|

Under the SEGM statement for DEALER, the first Field statement identifies anexisting 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 identifiedcorrectly, 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 andlength. If such a field exists, it is assigned the Java name, DealerName. Thisabbreviated method of identifying the field achieves the same result, but is not quiteso safe because no 8-character name check is carried out. The data type forDealerName 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 FIELDmacro in the DBD. It specifies the start position and length of this field, assigns it aJava name of DealerAddress, and a type of CHAR.

SEGM DBDName=DEALERDB SegmentName=DEALER JavaName=DEALERXXFIELD Name=DLRNO Start=1 Bytes=4 JavaType=CHAR JavaName=DealerNumberFIELD Start=5 Bytes=30 JavaType=CHAR JavaName=DealerNameFIELD Start=35 Bytes=50 JavaType=CHAR JavaName=DealerAddressFIELD Start=85 Bytes=10 JavaType=PACKEDDECIMAL TypeQualifier=S9(18) JavaName=YTDSales

SEGM DBDName=DEALERDB SegmentName=MODEL JavaName=MODELXXFIELD Name=MODTYPE Start=1 Bytes=2 JavaType=CHAR JavaName=ModelTypeCodeFIELD Name=MAKE Start=3 Bytes=10 JavaType=CHAR JavaName=CarMakeFIELD Name=MODEL Start=13 Bytes=10 JavaType=CHAR JavaName=CarModelFIELD Name=YEAR Start=23 Bytes=4 JavaType=CHAR JavaName=CarYearFIELD Name=MSRP Start=27 Bytes=5 JavaType=CHAR JavaName=PriceFIELD Start=32 Bytes=4 JavaType=CHAR JavaName=EPACityMilageFIELD Start=36 Bytes=4 JavaType=CHAR JavaName=EPAHighwayMilageFIELD Start=40 Bytes=4 JavaType=CHAR JavaName=Horsepower

SEGM DBDName=DEALERDB SegmentName=ORDER JavaName=ORDERXXFIELD Name=ORDNBR Start=1 Bytes=6 JavaType=CHAR JavaName=OrderNumberFIELD Start=7 Bytes=30 JavaType=CHAR JavaName=OptionsFIELD Start=37 Bytes=5 JavaType=ZONEDDECIMAL TypeQualifier=99999 JavaName=PriceFIELD Start=42 Bytes=8 JavaType=CHAR JavaName=OrderDateFIELD Name=LASTNME Start=50 Bytes=25 JavaType=CHAR JavaName=PurchaserLastNameFIELD Name=FIRSTNME Start=75 Bytes=25 JavaType=CHAR JavaName=PurchaserFirstNameFIELD Start=100 Bytes=8 JavaType=CHAR JavaName=SerialNoFIELD Start=120 Bytes=8 JavaType=CHAR JavaName=DeliverDate

SEGM DBDName=DEALERDB SegmentName=SALES JavaName=SALESXXFIELD Name=SALDATE Start=1 Bytes=8 JavaType=CHAR JavaName=DateSoldFIELD Name=LASTNME Start=9 Bytes=25 JavaType=CHAR JavaName=PurchaserLastNameFIELD Name=FIRSTNME Start=34 Bytes=25 JavaType=CHAR JavaName=PurchasetFirstNameFIELD Start=59 Bytes=25 JavaType=CHAR JavaName=PurchaserAddressFIELD Start=84 Bytes=10 JavaType=CHAR JavaName=SoldByFIELD Name=STKVIN Start=94 Bytes=20 JavaType=CHAR JavaName=StockVINumber

SEGM DBDName=DEALERDB SegmentName=STOCK JavaName=STOCKXXFIELD Name=STKVIN Start=1 Bytes=20 JavaType=CHAR JavaName=StockVINumberFIELD Start=21 Bytes=8 JavaType=CHAR JavaName=DateInFIELD Start=29 Bytes=8 JavaType=CHAR JavaName=DateOutFIELD Name=COLOR Start=37 Bytes=10 JavaType=CHAR JavaName=ColorFIELD Name=PRICE Start=47 Bytes=5 JavaType=ZONEDDECIMAL TypeQualifier=99999 JavaName=PriceFIELD Name=LOT Start=53 Bytes=10 JavaType=CHAR JavaName=Lot

Figure 53. Second-Level Control Data Set for Multiple Control Statements Example



|||||||||||||||||||||||||||||||||||||||||

||||||||

|||||

||||

The fourth Field statement defines another new field, YTDSales, of typePACKEDDECIMAL. This data type requires a type qualifier that defines the fieldformat, and in this example, a qualifier of S9(18) is supplied.

The remainder of the control statements describe information for the othersegments and fields in the DBD in a similar manner. When DLIModel is executed, itgenerates the DLIModel Java Report in Figure 23, together with a matchingmetadata class (not shown here).

In this DLIModel Java Report, the names of segments and fields are the Javanames supplied in the control statements. The eight-character IMS names do notappear because the Java developer does not need to know these names.

DLIModel Java Report========================Class: DealerDatabaseView generated for PSB: DLR_PSB

==================================================PCB: DealershipDB==================================================Segment: DEALERxxField: 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=50Field: YTDSales Type=PACKEDDECIMAL Type Qualifier=S9(18) Start=85 Length=10==================================================

Segment: MODELXXField: 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=4Field: EPAHighwayMilage Type=CHAR Start=36 Length=4Field: Horsepower Type=CHAR Start=40 Length=4==================================================

Segment: ORDERXXField: 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=30Field: Price Type=ZONEDDECIMAL Type Qualifier=99999 Start=37 Length=5Field: OrderDate Type=CHAR Start=42 Length=8Field: SerialNo Type=CHAR Start=100 Length=8Field: DeliverDate Type=CHAR Start=120 Length=8==================================================Segment: SALESXXField: DateSold Type=CHAR Start=1 Length=8 ++ Primary Key Field ++Field: PurchaserLastName Type=CHAR Start=9 Length=25 (Search Field)Field: PurchasetFirstName Type=CHAR Start=34 Length=25 (Search Field)Field: StockVINumber Type=CHAR Start=94 Length=20 (Search Field)Field: PurchaserAddress Type=CHAR Start=59 Length=25Field: SoldBy Type=CHAR Start=84 Length=10==================================================

Segment: STOCKXXField: StockVINumber Type=CHAR Start=1 Length=20 ++ Primary Key Field ++Field: Color Type=CHAR Start=37 Length=10 (Search Field)Field: Price Type=CHAR Start=47 Length=5 (Search Field)Field: Lot Type=CHAR Start=53 Length=10 (Search Field)Field: DateIn Type=CHAR Start=21 Length=8Field: DateOut Type=CHAR Start=29 Length=8

Figure 54. DLIModel Java Report for Multiple Control Statements Example



|||||||||||||||||||||||||||||||||||||||||||||||||

|||

|||

|||||

|||

Chapter 6. Problem Determination

This chapter contains information on debugging your IMS Java programs anddetermining 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

ExceptionsExceptions are thrown as a result of non-blank status codes and non-zero returncodes (in cases when there were no PCBs to deliver status codes) from IMS DL/Icalls. Even though an exception is thrown by JavaToDLI for every non-blank statuscode, some of these exceptions are caught by the application or databasepackages and converted to return values.

How Exceptions Map to DL/I Status CodesIMSException extends java.lang.Exception.

DLIException extends IMSException. Exceptions of this type include all errors thatoccur 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:

getAIBReturns the IMS AIB from the DL/I call that caused the exception. IMS AIBis null for DLIException. The methods on the AIB can be called to returnother information at the time of the failure, including the resource or PCBname and the PCB itself.

getStatusCodeReturns 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 iszero (0) for a DLIException.

getFunctionReturns 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 returnfalse if they receive GB (no more such segments or segment not found) or GE (nosuch segment or end of database) status codes and they are consumed byDLIConnection.


|||

|||||

The IMSMessageQueue.getUniqueMessage method returns false if it receives a QC(no more messages) status code. The IMSMessageQueue.getNextMessage methodreturns 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:

Related Reading: For more information on DL/I Status Codes see IMS Version 7Application Programming: Database Managerand IMS Version 7 ApplicationProgramming: Transaction Manager.

SQLExceptionsSQLException is thrown to indicate that an error has occurred either in the Javaaddress 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 SQLspecification.

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.

DLIConnection.getUniqueSegmentDLIConnection.getNextSegmentDLIConnection.getUniqueRecordDLIConnection.getNextRecordDLIConnection.getNextSegmentInParent

Figure 55. Database access methods of DLIConnection

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

Exceptions


|

Sync Point FailureIf you receive an SY DL/I PCB status code, your IMS Java application SYNCrequest call has failed. Table 6 describes the failure.

Table 6. Status Code, Reason, and Return Code

DL/IReturn/ReasonCode

PCBStatusCode

SystemServiceCall

Category Description

0108/056C

SY IMS Javasync

5 Internal error during sync point processing foran 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 FailureIf you receive a CR DL/I PCB status code, your IMS Java application GU messagerequest call has failed. Table 7 describes the failure. Correct your application toissue a Java commit prior to issuing your next GU message call.

Table 7. Status Code, Reason, and Return Code

AIBReturn/ReasonCode

PCBStatusCode

SystemServiceCall

Category Description

0104/0300

CR IMS JavaGU

Message

4 Application error during GU messageprocessing for an IMS Java application.

AbendsAn abend is the abnormal ending of a program or application. When an abend errorcondition occurs, an abend macro is issued either at the point of error detection orby branching to a routine that issues the abend macro. There are alsopseudoabends in which the module that detects the error condition does not issuethe 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 logand indicates a dependent-region abend.

Following are the abends that you might encounter as a result of errors whilerunning IMS Java applications.

ABENDU0118 - Commit FailureThis abend is issued if your IMS Java application attempts to terminate withoutcalling IMSTransaction.commit. An explicit commit is required for each IMS Javaapplication before it can terminate normally.

Related Reading: For more information on ABENDU0118, see IMS Version 7Failure Analysis Structure Tables (FAST) for Dump Analysis and IMS Version 7Messages and Codes, Volume 1.

Sync Point Failure

Chapter 6. Problem Determination 93

|

|||

||

||||

|||

|||

||

||||||

|||

|||

ABENDU0475 - Batch Run FailureThis abend is issued if your IMS Java application attempts to run as an IMS Batchjob. IMS batch does not currently support IMS Java applications.

Related Reading: For more information on ABENDU0475, see IMS Version 7Failure Analysis Structure Tables (FAST) for Dump Analysis, and IMS Version 7Messages and Codes, Volume 2.

Processing DumpsYou might be asked to help interpret a dump for diagnostic purposes.

Related Reading:

v For more information on dump processing, see IMS Version 7 InstallationVolume 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 AnalysisStructure Tables (FAST) for Dump Analysis and the IMS Version 7 DiagnosisGuide and Reference.

DLIModel MessagesThis section describes the messages that are issued by the DLIModel utility.

The DLIModel utility message number severity suffixes are as follows unlessotherwise indicated:

E Unrecoverable error

W Warning

I Informational message

DHM0001 System Error: text (class/method)(DHM0001E)

Explanation: This message describes a probable errorin the DLIModel utility during the import of a PSB orDBD.

text -describes the problem

(class/method)-describes the location; class or method name,in DLIModel at which the error was detected

(DHM00001E)-the message reference number

Programmer Response: Call IBM for service. Havethese things available:

v the content of this message

v the input PSBs and all related DBDs

v control statement data set or file

v the JCL or USS command that you used to executethe utility

Problem Determination: You may be asked to rerunDLIModel with the option parameter, Trace=yes set inorder to aid in the problem determination.

DHM0002 through DHM0199 text (class/method)(DHM0xxxE)

Explanation: Messages in this range describeproblems in the input data that prevent the utility fromcontinuing during the import of a PSB or DBD. As aresult, the utility terminates.


(class/method)-describes the location; class or method name,in DLIModel at which the error was detected

(DHM0xxxE)-the message reference number

xxx the last three digits of the messagenumber, in the range: 2 through 199

Programmer Response: Typically, this error is theresult of incorrect or inconsistent PSB or DBD sourcedata. It is strongly recommended that PSBs and DBDsare compiled, an ACBGEN is performed, and all errorsare corrected before running the DLIModel utility. Ifthese tasks are not done, there is no guarantee that theDLIModel utility will detect all potential errors in the PSB

Sync Point Failure


|

|

||

||

||

||

||||

|||

||

|||

||

||

|

|

|

||

|||

|||

||||

||

|||

||

|||

|||||||

or DBD source, so the resulting output might beincomplete or incorrect.

If the PSBs and the DBDs have been validated (throughPSBGEN, DBDGEN, and ACBGEN) but the problempersists, call IBM for service. Have these thingsavailable:


v the input PSBs and DBDs

v the control statement data set or file


Problem Determination: You may be asked to rerunDLIModel with the option parameter, Trace=yes set inorder to aid in the problem determination.

DHM0200 through DHM0299 text (DHM02xxW)

Explanation: These messages describe warnings ofproblems with the input data that did not prevent theDLIModel utility from continuing. In most cases part ofthe input data is ignored in order to circumvent theproblem, and this might result in incomplete output.


(DHM02xxW)-the message reference number

xx the last two digits of the messagenumber, in the range: 0 through 99

Programmer Response: The utility output (forexample the IMS Java metadata classes) should becarefully reviewed before use. In some cases the outputwill be usable after one of these warnings -- forexample, a PSB may contain a PCB that references anMSDB type database, which cannot be handled by theutility. The generated IMS Java classes report of theXMI file will omit the MSDB database, that wouldtypically be acceptable for an IMS Java application thatused the metadata classes.

DHM0500 through DHM0599 text (DHM05xxy)

Explanation: These messages describe standardactions taken, warnings, and errors that occur duringthe processing of the DLIModel control statement file.


(DHM05xxy)-the message reference number


y one of these severities:

I informational

W warning

E error

Programmer Response:

Informational messages:Confirm that the action that was performed bythe utility is acceptable.

Warning messages:These messages describe an error that couldbe corrected or ignored by the utility, allowing itto continue,. Frequently this is done by ignoringpart of one or more control statements.

Confirm that the action that was performed bythe utility is acceptable by reviewing themessage and the generated output. Correctand rerun the utility if necessary.

Error messages:These messages describe an error that causedthe utility to terminate. Correct the error andrerun the utility. In some cases, one of thesemessages is followed by related messages thatdescribe a system error, or an error or awarning regarding input data.

DHM0800W through DHM0899W text (DHM008xxE)

Explanation: These messages describe errors thatoccur during the export of the IMS Java metadataclasses and the Java report.


(DHM08xxE)-the message reference number


Programmer Response: Message DHM0800Edescribes problems that are probable system errors.Call IBM for service. Have the following things available:the content of this message, the input PSB and allrelated DBDs, control statement data set or file, and theJCL or USS command that was used to execute theutility

Other messages in this range are often caused byincorrect or inconsistent PSB or DBD source data. It isstrongly recommended that PSBs and DBDs becompiled, an ACBGEN performed, and all errorscorrected before running the DLIModel utility. If thesetasks are not done, there is no guarantee that theDLIModel utility will detect all potential errors in the PSBor DBD source, and the export of IMS Java entities mayfail, resulting in one of these messages.

If the PSBs and the DBDs have been validated (throughPSBGEN, DBDGEN, and ACBGEN) but the problempersists, call IBM for service. Have these thingsavailable:


v the input PSBs and DBDs

v the control statement data set or file

DLIModel Messages


||

||||

|

|

|

||

|||

||

|||||

||

||

|||

||||||||||

||

|||

||

||

|||

||

||

||

||

|

|||

|||||

||||

|||||||

||

|||

||

||

|||

|||||||

|||||||||

||||

|

|

|


Problem Determination: You may be asked to rerun

DLIModel with the option parameter, Trace=yes set inorder to aid in the problem determination.

IMSTraceWith IMSTrace, you can debug your Java applications by tracing, or documenting,the flow of control throughout your application. By setting up tracepoints throughoutyour applications for output, you can isolate problem areas and, therefore, knowwhere to make adjustments to produce the results you expect. In addition, becauseIMSTrace supports writing input parameters and results, and theIMS-Java-library-provided routines use this feature, you can verify that correctresults occur across method boundaries.

IMSTrace is distinct from the DLIModel utility trace. For information on how to setthe DLIModel utility trace, see “OPTIONS Statement” on page 68.

Initiating IMSTracingTo debug with IMSTrace, you must first turn on the tracing function by setting theIMSTrace.traceOn variable to true. Because tracing does not occur until thisvariable 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 ofcontrol, 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 ofIMSTrace.libTraceLevel to one of its predefined values. By default, this value is setto IMSTrace.TRACE_EXCEPTIONS, which traces the construction ofIMS-Java-library-provided exceptions. IMSTrace also defines constants for threetypes of additional tracing. These constants provide successively more tracing fromIMSTrace.TRACE_CTOR1 (level one tracing of constructions) toIMSTrace.TRACE_DATA3 (level three tracing of data).

Setting up Tracing for the IMS Java Library RoutinesTo 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 currenttrace 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, asshown in Figure 57 on page 97:

DLIModel Messages


||

|

||

|

|||||

|

|

|

||

|

||

|

|

|

||

|||

Adding Trace Statements to Your ApplicationYou can add trace statements to your application, similar to those provided by theIMS Java Library, by defining an integer variable that you test prior to writing tracestatements. Using a variable other than IMSTrace.libTraceLevel enables you tocontrol the level of tracing in your application independently of the tracing in theIMS Java library. For example, you can turn off the tracing of IMS Java Libraryroutines by setting IMSTrace.libTraceLevel to zero but still trace your applicationcode.

Follow these steps to add tracing to your application code:

1. Define an integer variable to contain the trace level for application-providedcode:public class IMSAuto extends IMSApplication {

public int applicationTraceLevel = IMSTrace.TRACE_CTOR3;

2. Set up IMSTrace to trace methods, parameters, and return values as necessary,as shown in Figure 58:

public class IMSAuto extends IMSApplication {

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

public class IMSAuto extends IMSApplication {

public static int applicationTraceLevel=IMSTrace.TRACE_CTOR3;

static {

IMSTrace.traceOn = true;

IMSTrace.libTraceLevel = IMSTrace.TRACE_METHOD1;

IMSTrace.setOutputStream(System.err);

}

public static void main (String args[]) {

IMSAuto application = new IMSAuto();

application.begin();

}

Figure 58. Setting Up IMSTrace (Part 1 of 3)

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;

}


IMSTrace


Appendix A. Manually Creating IMS Java Metadata Classes

This appendix describes the procedure for manually creating the metadata classesrequired for JDBC access to IMS databases.

Note: The recommended method for creating these classes is to use the DLIModelutility, described in Chapter 5, “DLIModel Utility” on page 61.

Mapping an IMS Database in Java ClassesTo map an IMS database in Java classes, you use the segments and fields in theDatabase Definition (DBD) to create DLIDatabaseView and DLISegmentsubclasses. The hierarchical database shown in Figure 59 is used as the sampledatabase in the code examples that follow.

IMS Database Definition (DBD)The Database Definition (DBD) is set up by the database administrator. A DBDdefines the segments (″SEGM NAME″) and key fields (″FIELD NAME″) of thedatabase. Figure 60 on page 100 is the DBD for the sample hierarchical databasein Figure 59.

Adding Default Values for Fields of a SegmentIn certain cases, you might want to assign a default value for a particular Field of aSegment definition. You may want the defaults, for example, when assigning valuesthat may not be set in the application, or for reducing the amount of requiredapplication setup for insert segment calls. To assign an initial default value manuallymodify the constructor for the generated DLIDatabaseView subclass.

After the super() and any addDatabase() calls in the generated DLIDatabaseViewsubclass, a setString(), setInt(), or any setXXX() call can be made to set thedefault value. This default value remains constant throughout the application and sowill exist in all cloned instances of the Segment.

The following example demonstrates how to add a default value of Chris to thePersonalHero Field of the Employee Segment:

Figure 59. Example Database and Segments


|

|

||

||

||

||||||

|

||||

|

|||||

||||

||

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);

//Constructorpublic EmpPSB1DatabaseView() {

super("EMPPSB1", "pcb1", "PCB1", PCB1array);addDatabase("pcb2", "PCB2", PCB2array);

// Set DefaultPCB1EMPLOYEESegment.setString("PersonalHero", "Chris");

}try {// Set Default... } catch (com.ibm.ims.db.DLIException e) {throw new RuntimeException(e.toString()); }

Mapping the PSB to DLIDatabaseViewThe PSB (Program Status Block) defines a grouping of resources available to anapplication. Included in the PSB is a DB PCB (Database Program CommunicationBlock) definition for each database that your application can access.

The DB PCB defines the access rights that your application has to the segments ofthe database. In particular, a database PCB (PCB Type=DB) defines whichsegments, and which fields within those segments, your program can access, andthe access intent (such as get, insert, replace, delete, or all) and isolation level(such as dirty read) that is used when accessing a database by way of that PCB.

DBD NAME=DEALERDB,ACCESS=(HDAM,OSAM),RMNAME=(DFSHDC40.1.10)SEGM NAME=DEALER,PARENT=0,BYTES=94,FIELD NAME=(DLRNO,SEQ,U),BYTES=4,START=1,TYPE=CFIELD NAME=DLRNAME,BYTES=30,START=5,TYPE=CSEGM NAME=MODEL,PARENT=DEALER,BYTES=43FIELD NAME=(MODTYPE,SEQ,U),BYTES=2,START=1,TYPE=CFIELD NAME=MAKE,BYTES=10,START=3,TYPE=CFIELD NAME=MODEL,BYTES=10,START=13,TYPE=CFIELD NAME=YEAR,BYTES=4,START=23,TYPE=CFIELD NAME=MSRP,BYTES=5,START=27,TYPE=PSEGM NAME=ORDER,PARENT=MODEL,BYTES=127FIELD NAME=(ORDNBR,SEQ,U),BYTES=6,START=1,TYPE=CFIELD NAME=LASTNME,BYTES=25,START=50,TYPE=CFIELD NAME=FIRSTNME,BYTES=25,START=75,TYPE=CSEGM NAME=SALES,PARENT=MODEL,BYTES=113FIELD NAME=(SALDATE,SEQ,U),BYTES=8,START=1,TYPE=CFIELD NAME=LASTNME,BYTES=25,START=9,TYPE=CFIELD NAME=FIRSTNME,BYTES=25,START=34,TYPE=CFIELD NAME=STKVIN,BYTES=20,START=94,TYPE=CSEGM NAME=STOCK,PARENT=MODEL,BYTES=62FIELD NAME=(STKVIN,SEQ,U),BYTES=20,START=1,TYPE=CFIELD NAME=COLOR,BYTES=10,START=37,TYPE=CFIELD NAME=PRICE,BYTES=5,START=47,TYPE=CFIELD NAME=LOT,BYTES=10,START=53,TYPE=CDBDGENFINISHEND

Figure 60. DBD Sample Definition


|||||||||||||||||||||||||||

|||

||||||||||||||||||||

|

|||

||||||

You define the information that is needed to connect to one or more databases fromwithin an application with the DLIDatabaseView. In IMS Java, the DLIDatabaseViewclass contains metadata (information describing the data in the database, such astypes and lengths of fields) that describes your application’s view of the databasesthat 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 theDBD, 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 PSBdefinition.

v The fields defined within a segment. These are usually defined only within theDBD, but their use may be restricted by the SENFLD macro in the PSBdefinition. Figure 61 on page 102 shows the PSB definition for the Dealershipapplication.

DLIDatabaseView ExampleUsing information from the PSB shown in Figure 61 on page 102, create aDLIDatabaseView subclass called DealerDatabaseView. The numbers in thefollowing list (for example, �1�) are referenced in Figure 61 on page 102. Note thefollowing:

v Within the subclass you create an array of DLISegmentInfo objects, one entry foreach DLISegment object used by the application. �1� As you will see in“DLISegment Example” on page 103, a DLISegment object defines the fields in adatabase segment similar to the way an IMSFieldMessage object defines thefields 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 entryfor the Order segment specifies an index of 1, which is the index in the array forthe Model segment.

v The parent of the root segment, Dealer, is specified by the constantDLIDatabaseView.ROOT to indicate that it has no parent. �3�

v The dealer PSB name, DLR_PSB, is passed in the DealerDatabaseViewconstructor to the super class constructor along with the array of DLISegmentInfoobjects. �4�

Appendix A. Manually Creating IMS Java Metadata Classes 101

||||||

||

|

|

||

||||

|

||||

|||||

||||

||

|||

|

import com.ibm.ims.db.*;import com.ibm.ims.base.*;

public class DealerDatabaseView extends DLIDatabaseView {

static DLITypeInfo[] dealerInfo = {new DLITypeInfo("DealerNo",DLITypeInfo.CHAR, 1, 4, "DLRNO"),new DLITypeInfo("DealerName",DLITypeInfo.CHAR, 5, 30, "DLRNAME"),new DLITypeInfo("DealerCity",DLITypeInfo.CHAR, 35, 10, "CITY"),new DLITypeInfo("DealerZip",DLITypeInfo.CHAR, 45, 10, "ZIP"),new DLITypeInfo("DealerPhone",DLITypeInfo.CHAR, 55, 7, "PHONE"),

};static DLISegment dealerSegment = new DLISegment("DealerSegment",

"DEALER", dealerInfo, 61);// An array of DLITypeInfo objects to describe fields follows:static DLITypeInfo[] modelInfo = {

new DLITypeInfo("ModelType",DLITypeInfo.CHAR, 1, 2, "MODTYPE"),new DLITypeInfo("ModKey",DLITypeInfo.CHAR, 3, 24, "MODKEY"),new DLITypeInfo("Make",DLITypeInfo.CHAR, 3, 10, "MAKE"),new DLITypeInfo("Model",DLITypeInfo.CHAR, 13, 10, "MODEL"),new DLITypeInfo("Year",DLITypeInfo.CHAR, 23, 4, "YEAR"),new DLITypeInfo("MSRP",DLITypeInfo.CHAR, 27, 5, "MSRP"),new DLITypeInfo("Count",DLITypeInfo.CHAR, 32, 2, "COUNT"),

};static DLISegment modelSegment = new DLISegment("ModelSegment", "MODEL",

modelInfo, 37);// An array of DLITypeInfo objects to describe fields follows:

static DLITypeInfo[] orderInfo = {new DLITypeInfo("OrderNo", DLITypeInfo.CHAR, 1, 6, "ORDNBR"),new DLITypeInfo("LastName", DLITypeInfo.CHAR, 7, 25,"LASTNME")new DLITypeInfo("FirstName", DLITypeInfo.CHAR, 32, 25,"FIRSTNME"),new DLITypeInfo("Date", DLITypeInfo.CHAR, 57, 10, "DATE"),new DLITypeInfo("Time", DLITypeInfo.CHAR, 67, 8, "TIME"),

};static DLISegment orderSegment = new DLISegment("OrderSegment",

"ORDER", orderInfo, 74);// An array of DLITypeInfo objects to describe fields follows:static DLITypeInfo[] salesInfo = {

new DLITypeInfo("SaleNo", DLITypeInfo.CHAR, 1, 4, "SALENUM"),new DLITypeInfo("SaleDate", DLITypeInfo.CHAR, 5, 8, "SALDATE"),new DLITypeInfo("LastName", DLITypeInfo.CHAR, 13, 25, "LASTNME"),

};static DLISegment salesSegment = new DLISegment("SalesSegment", "SALES",

salesInfo, 37);static DLITypeInfo[] stockInfo = {

new DLITypeInfo("StockVin", DLITypeInfo.CHAR, 1, 20, "STKVIN"),new DLITypeInfo("Color", DLITypeInfo.CHAR, 21, 10, "COLOR"),new DLITypeInfo("Price", DLITypeInfo.CHAR, 31, 5, "PRICE"),new DLITypeInfo("Lot", DLITypeInfo.CHAR, 36, 10, "LOT"),new DLITypeInfo("Warranty", DLITypeInfo.CHAR, 46, 1, "WRNTY"),

};static DLISegment stockSegment = new DLISegment("StockSegment", "STOCK",

stockInfo, 46);// An array of DLISegment objects to describe PSB viewstatic 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


|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||

|||

In our dealership example, there is only a single PCB defined in the dealershipPSB. If there were other PCBs defined, they would be added to theDLIDatabaseView 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 tosuper, and passing the reference name of the PCB, the real name of the PCB,and the variable defining the array of DLISegmentInfo objects.

DLISegment ExampleUsing the extracted database name and segment names from Figure 60 onpage 100, you create a DLISegment dealer. The numbers in the following list (forexample, �1�) are referenced in Figure 62. Note the following:

v You create an array of DLITypeInfo objects, one entry for each field used by theapplication. �1�

v Each DLITypeInfo object defines the name, type, starting offset, length, andoptionally the name of the field in the DBD. If you want to search on a field in aDLITypeInfo 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 bytesand is not defined in the DBD. �2� To search on a field, the field name must bedefined in the DBD file, and the field name as listed in the DBD must be providedto the DLITypeInfo object.

v The segment name, DEALER, is passed in the Dealer constructor to theDLISegment constructor with the array of DLITypeInfo objects and the length ofthe entire array. �3� The easiest way to calculate that length is to add the startingoffset 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 OptionsIMS does not support setting environmental variables before running an application;instead, you must set any environmental variables needed by an application atcompile time. The following options must be set at compile time:

-lerunopts=″ENVAR″Allows environment variables to be defined in the executable for use atruntime. Set the following environment variables with this option:

CLASSPATHAn environment variable used during runtime to locate class files.CLASSPATH must be set to point to the imsjava library code, andthe 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_HOMEIdentifies the root of the hpj files, and is used to locate hpj librariesat runtime. It is typically /usr/lpp/hpj.

LIBPATHIdentifies additional locations for runtime to search for library files.In particular, it can be used to find a UNIX link to the IMS Javanative code library if the installation default is changed. Atinstallation, this link is /usr/lpp/ims/imsjava71/libJavTDLI.dll, whichpoints to the PDSE member DFSCLIB. You can create the UNIXlink libJavTDLI.so to point to DFSCLIB in any location included inthe LIBPATH.

-includeUse this option of the hpj command to include objects in your executable.Objects that need to be included are those that are dynamically loaded atruntime. For example, if you provide your database view as a string insteadof creating an instance of the view in your application, you must include thatstring in your executable. This option is necessary any time you are writingJDBC applications. You must include all database views. An example of the-include option follows:-include=dealership.application.DealerDatabaseView

-excludeUse this option of the hpj command to exclude objects from being staticallybound to your executable. The exclude statements in Figure 63 onpage 106 illustrate how to dynamically access the IMS Java classes:


||

-main=classnameUse 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. Althoughyou can use the -make option when building a Java executable or DLL forthe first time, you normally use this option when you are doing incrementalrebind to refresh an existing Java executable or DLL.

-target=IMSUse this required option to indicate that the program will be an IMSapplication.

-o=executableUse this option to explicitly name the Java executable or DLL that you arebuilding in the hfs file system or as a PDSE (partitioned dataset extended)member.

-alias=nameUse this option to specify an alias or hierarchical file system (HFS), such asthe name for a Java executable or DLL that is being written to a PDSEmember. The option -alias must be specified for all Java DLLs that reside inPDSE members.

Your application containing the main has to be in a PDSE. To build an applicationas 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/*.javajavac dealership/database/*.java

3. Bind the class files into an executable member named IMSAUTO of the PDSEAUTO.DEALERSHIP:

-exclude=com.ibm.ims.base.*

-exclude=com.ibm.ims.application.*

-exclude=com.ibm.ims.db.*

Figure 63. -exclude statement example

hpj -make dealership.application.IMSAuto \-main=dealership.application.IMSAuto \-o="//’AUTO.DEALERSHIP(IMSAUTO)’" \-alias=IMSAUTO \-target=IMS \-lerunopts="ENVAR(’CLASSPATH=/usr/lpp/hpj/lib:/usr/lpp/ims/imsjava71/imsjava.jll ’, ’IBMHPJ_HOME=/usr/lpp/hpj ’)" \-exclude=com.ibm.ims.db.* \-exclude=com.ibm.ims.application.* \-include=dealership.application.DealerDatabaseView \-exclude=com.ibm.ims.base.*

Figure 64. Binding the class files


Installation Verification ProcessThe following are example steps to verify an IMS Java install.

1. Go to the directory in which IMS Java is installed:cd usr/lpp/ims/imsjava71

2. Compile the IVP Java programs:javac samples/ivp/*.java

3. Create the executable load module and put it in the IVP PGMLIB data set(which should be pre-allocated):hpj samples.ivp.IVP -main=samples.ivp.IVP \

-o="//’IVPEXEXX.PGMLIB(DFSIVP32)’" -alias=DFSIVP32 \

-target=IMS \

-lerunopts="ENVAR(’CLASSPATH=/usr/lpp/hpj/lib:/usr/lpp/ims/imsjava71/imsjava.jll ’, ’IBMHPJ_HOME=/usr/lpp/hpj ’)"

4. Add the IVP PGMLIB data set to the STEPLIB in the JCL that starts the IMSMPP region. In the installation verification process, this data set must comebefore any other data set with the same name (DFSIVP32) in the STEPLIBconcatenation. The first data set with that name in the STEPLIB is the one thatwill be executed.STEPLIB DD DSN=IVPEXEXX.PGMLIB,DISP=SHR

5. Include the data set for the IMS Java class libraries and hpj class libraries inthe STEPLIB:DD DSN=hlq.SDFSJLIB,DISP=SHRDD DSN=VAJAVA.V2R0M0.SHPJMOD,DISP=SHRDD DSN=VAJAVA.V2R0M0.SHPOMOD,DISP=SHR

The HLQ (High Level Qualifier) is the PDSE that you specified during theinstallation process for IMS Java.

6. Change the version number of the HPJ to reflect the correct version of HPJinstalled.

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

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:



PROCESS CODE (*1) :(*1) PROCESS CODE

LAST NAME : ADDDELETE



INTERNAL ZIP CODE :

SEGMENT# :

Figure 65. Example of a Blank IMS Installation Verification Procedure Screen







INTERNAL ZIP CODE :

SEGMENT# :

Figure 66. Example IMS Installation Procedure Screen with Transaction Input Information






FIRST NAME : FIRST1 UPDATEDISPLAY

EXTENSION NUMBER : 8-111-1111 TADDEND

INTERNAL ZIP CODE : D01/R01

ENTRY WAS DISPLAYED SEGMENT# :

Figure 67. Example IMS Installation Verification Procedure Screen with Transaction OutputInformation

Appendix B. High Performance Java 109

Bibliography

This bibliography includes all the publications citedin this book, including the publications in the IMSlibrary.

IBM Developer Kit for OS/390, Java 2Technology Edition: New IBM Technologyfeaturing Persistent Reusable Java VirtualMachines, SC34-6034

IMS Primer, SG24-5352

OS/390: Unix Systems Services CommandReference, SC28-1892

OS/390: Unix System Services File SystemInterface Reference, SC28-1909

OS/390: Unix Systems Services User’s Guide,SC28-1891

CICS Transaction Server for OS/390: CICSSystem Definition Guide, SC33-1682

WebSphere Application Server V4.0.1 for z/OSand OS/390 : Assembling Java 2 Platform,Enterprise Edition (J2EE) Applications,SA22-7836

WebSphere Application Server V4.0.1 for z/OSand OS/390 : System Management UserInterface, SA22-7838

IMS Version 7 Library

SC26-9419 ADB IMS Version 7 AdministrationGuide: Database Manager

SC26-9420 AS IMS Version 7 AdministrationGuide: System

SC26-9421 ATM IMS Version 7 AdministrationGuide: Transaction Manager

SC26-9422 APDB IMS Version 7 ApplicationProgramming: DatabaseManager

SC26-9423 APDG IMS Version 7 ApplicationProgramming: Design Guide

SC26-9424 APCICS IMS Version 7 ApplicationProgramming: EXEC DLICommands for CICS andIMS

SC26-9425 APTM IMS Version 7 ApplicationProgramming: TransactionManager

SC26-9427 CG IMS Version 7 CustomizationGuide

SC26-9426 CQS IMS Version 7 CommonQueue Server and BasePrimitive Environment Guideand Reference

SC26-9436 CR IMS Version 7 CommandReference

SC26-9428 DBRC IMS Version 7 DBRC Guideand Reference

LY37-3738 DGR IMS Version 7 DiagnosisGuide and Reference

LY37-3739 FAST IMS Version 7 FailureAnalysis Structure Tables(FAST) for Dump Analysis

SC27-0832 IJUG IMS Version 7 IMS JavaUser’s Guide

GC26-9429 IIV IMS Version 7 InstallationVolume 1: Installation andVerification

GC26-9430 ISDT IMS Version 7 InstallationVolume 2: System Definitionand Tailoring

SC26-9432 MIG IMS Version 7 Master Indexand Glossary

GC26-9433 MC1 IMS Version 7 Messages andCodes, Volume 1

GC26-1120 MC2 IMS Version 7 Messages andCodes, Volume 2

SC26-9434 OTMA IMS Version 7 OpenTransaction Manager AccessGuide

SC26-9435 OG IMS Version 7 OperationsGuide

GC26-9437 RPG IMS Version 7 ReleasePlanning Guide

SC26-9438 SOP IMS Version 7 SampleOperating Procedures

SC26-9440 URDBTM IMS Version 7 UtilitiesReference: Database andTransaction Manager

SC26-9441 URS IMS Version 7 UtilitiesReference: System

Supplementary Publications

GC26-9431 LPS IMS Version 7 LicensedProgram Specifications

SC26-9439 SOC IMS Version 7 Summary ofOperator CommandsSummaryof Operator Commands

Publication Collections

LK3T-3526 CD IMS Version 7 LicensedProduct Kit: Online Library

LBOF5294 Hardcopyand CD

Licensed Bill of Forms (LBOF):IMS Version 7 Hardcopy andOnline Library


||||

|

||

||

||

||

||||

|||

Publication Collections

SBOF5297 Hardcopy Unlicensed Bill of Forms(SBOF): IMS Version 7Unlicensed Hardcopy Library

SK2T-0730 CD IBM Online Library: TransactionProcessing and Data

SK2T-6700 CD IBM Online Library OS/390


Index

Special characters-exclude 105-include 105

Aabends

0118 930475 94batch run failure 94commit failure 93description 93

ABENDU0118 93ABENDU0475 94adding Trace statements to applications 97aggregate keywords 35AIB interface 3AIBERRXT 93applications

batch 2CICS environment 59DB2 environment 59JBP 2JMP 2message driven 2message processing, building 46non-message driven 2processing 46programming 42that work with IMS 45

asterisk operator 38

Bbatch programs 45batch run failure 94BIGINT data type 32BINARY data type 32BIT data type 32buffers

main storage 46byte data type 32

CCHAR data type 32CICS

configuring for IMS Java 13CICS environment

IMS Java application 59installation verification 14overview 2programming model 59restrictions 13system requirements 13

classDLIDatabaseView 41

class (continued)DLIRecord 41DLISegment 41DLISegmentInfo 41DLITypeInfo 41java.sql.DatabaseMetaData 31java.sql.Driver 31java.sql.Statement 31SSAQualificationStatement 41

CLASSPATH 16COBOL

copybook types 33mapping to IMS 33

command input 46commit 31commit failure 93configuration

CICS environment 13WebSphere for z/OS environment 9

Connection objectexecuting 29

Connection.commit 31Connection.rollback 31Connection.setAutoCommit 31control statements

DLIModel utility 62, 66example 85format 68including 73syntax 74typical sequence 67when to use 67

controlling the amount of tracing 96conventions

naming 28conversational transactions 52copybook types 33

Ddata types

conversion 32mapped to COBOL 33

database metamodelXMI 65

database segmentdescription 27

DATE data type 32DB2 environment

configuring 15ENVAR settings 16IMS Java applications 59installation verification 17overview 2programming model 59restrictions 15setup 15system requirements 15


DB2_HOME 16DBD (Database Definition)

example 25DD statements 75dealership sample

overview 23debugging 91

IMSTrace 96default values

assigning 99DELETE statement 39design process 1determining problems in your applications

IMSTrace 96DFHJVMPR 13DFSDLA00 93DFSJVMAP 5DFSJVMEV 5DFSMODEL member 19DFSTMS00 93DL/I data

accessing 43DL/I PCB status codes 93DL/I status codes

mapping to exceptions 91DLIConnection 41, 91

creating 42DLIDatabaseView 41

example 101mapping the DBD 100

DLIDriverloading 29registering 29

DLIException 91DLIModel Java Report

database summary 64example 25fields 27PCBs 26

DLIMODEL MVS Procedurepreparing 19

DLIModel utilitycontrol statements 62, 66description 61inputs and outputs 62limitations 63logical relationship example 79metadata classes

creating 61MVS procedure

EXEC statement 21script file 20

MVS USS prompt 21output types 64overview 61procedure 74PSB requirements 63report 61restrictions 64running 74running as MVS job 74

DLIModel utility (continued)running from USS 77secondary index example 83setup 19

MVS procedure 19simple example 77use 27using 61, 77

DLIRecord 41DLISegment 41

example 103DLISegmentInfo 41DLITypeInfo 41DLITypeInfoList 55doBegin()

implementing 48documenting an application’s flow of control 96DOUBLE data type 32driver

registering with DriverManager 29DriverManager 30DSNAME parameter 75dump processing 94

EEAR (Enterprise Archive) 11EJB (Enterprise Java Bean)

deploying 9overview 2

EJB (Enterprise Java Bean)deploying 11Enterprise Java Bean (EJB)

See EJB (Enterprise Java Bean) 2ENVIRON 5environments

CICSconfiguring 13installation verification 14overview 2restrictions 13system requirements 13

DB2configuring 15installation verification 17overview 2restrictions 15

generalrestrictions 3setup 3system requirements 3

IMSconfiguration 4installation verification 6JMP 4overview 1restrictions 2, 4setup 4system requirements 4

WebSphere for z/OSinstallation verification 12overview 2


environments (continued)WebSphere for z/OS (continued)

restrictions 8setup 8system requirements 8

EnvironmentsWebSphere for z/OS

EJB, deploying 11exceptions

description 91mapping to DL/I status codes 91

EXEC statement parameters 75

FField statement 67, 71fields

default values, assigning 99float data type 32FROM clause 37

GgenXMI parameter 65getAIB 91getFunction 91getNextException 92getStatusCode 91GU message failure 93

HHFS (Hierarchic File System) 3High Performance Java

See HPJ (High Performance Java) 107HPJ (High Performance Java)

compile options 105installation verification 107runtime options 105

Iimport statements 29IMS

application processing 45applications in Java 45call analyzer module 93

IMS databases(DBD) database definition 99accessing 23

JDBC 24mapping to Java classes 99relational, compared to 28

IMS environmentconfiguration 4installation verification 6overview 1restrictions 2

IMS Javaalias 28

IMS Java (continued)data type support 32databases supported 1dependent regions 1messages supported 1overview 1prerequisite knowledge xvrestrictions 3system requirements 3

IMS Java hierarchic database interfaceoverview 1, 23SSAs 23

IMS JDBC Connector 9IMS JDBC Resource Adapter

configuring 9deploying 10

IMSApplicationsubclassing 48

IMSException 91IMSFieldMessage 57

subclassing 47IMSJdbcCustomService.xml 10IMSMessageQueue 92IMSMessageQueue.getUniqueMessage 56IMSTrace 96include option 105Include statement 73index field

secondary 73initiating IMSTrace 96input

command 46message switch 46messages

defining 47transaction message 46

INSERT statement 38WHERE clause 38

installation verificationCICS environment 14DB2 environment 17IMS environment 6WebSphere for z/OS environment 12

int data type 32INTEGER data type 32IVP (installation verificaiton program)

See installation verification 14

JJ2EE server

configuring 9EJB, deploying 11IMS JDBC Resource Adapter, locating 9JVM properties 10modifying properties 9overview 2

java batch processing (JBPs) 45Java classes

mapping to IMS databases 99Java data types 32

Index 115

java message processing (JMPs) 45JAVA_HOME 16java.math.BigDecimal 32java.sql.Connection 30java.sql.DatabaseMetaData 31java.sql.Date 32java.sql.Driver 31java.sql.PreparedStatement 32java.sql.ResultSet 32java.sql.ResultSetMetaData 32java.sql.Statement 31java.sql.Time 32java.sql.Timestamp 32JAVAENV data set 16JBP (Java Batch Processing)

configuring 5overview 2

JBPs 45JDBC

classes 27Connection object, returning 29data types 32field names 27IMS databases

accessing 24interfaces, limitations 30overview 1, 23prerequisite knowledge xv

JMP (Java Message Processing)configuring 4overview 2

JMPs 45JVM

master 4worker 5

JVM regions, overview 1JVMOPMAS 4JVMOPWRK 5

Kkeywords

aggregate 35supported 35

LLIBPATH 16local transactions 3logical relationships

DLIModel utility example 79logical terminal (LTERM) 54long data type 32LTERM 54

Mmain storage buffers 46main() 48master JVM 4

message processing applicationbuilding 46

message processing applications 46message queue 46message switch input 46messages

inputdefining 47processing multiple 56retrieving 56

message queue in Java 46multi-segment 54output, defining 47reading and writing 46repeating structures

accessing 55SPA 52

metadata classcreating 24

metadata classescreating 61creating manually 99generated 64

multi-segment messages 54

Nnaming conventions

SQL 35nested structures

accessing 55

Oobject

DLIConnection 41DLIConnection, creating 42DriverManager 30java.sql.Connection 30SSA 41

ODBA (Open Database Access) 9options

include 105Options statement 66, 68output messages

defining 47

PP processing option 3package

database 30PACKEDDECIMAL data type 32PARM parameter 75path call 38PCB statement 67prepared statement 40PreparedStatement object 29, 36prerequisite knowledge xvproblem determination 91PROC statement parameters 75


processing applications 46processing dumps 94program types 45programming models

CICS environment 59DB2 environment 59JBP 51JMP 50

PRSUFFIX 14PSB

metadata class 61XMI description 61

PSB (Program Specification Block)example 25IMS Java metadata classes, relationship 24

PSB statement 66, 70

Qqueuing messages 46

RRational Rose

metamodel 66reason codes 93repeating structures

accessing 55report

DLIModel utility 61requirements, system 3restrictions 3

CICS environment 13DB2 environment 15WebSphere for z/OS 8

ResultSetiterating 29

return codes 93

Ssample

message processing application 46scratch pad area (SPA) 52secondary index

DLIModel utility example 83secondary index field 73SEGM statement 67, 70segment instances

querying 29segment search arguments (SSAs) 41segments

default values, assigning 99SELECT statement

asterisk operator 38description 35

setting up tracing 96short data type 32SMALLINT data type 32SPA 52, 54

SPA messagedefining 53

SQLDELETE statement 39FROM clause 37INSERT statement 38keywords 34, 35naming conventions 35prepared statement 40referring to Java Report 64SELECT statement 35supported grammar 34UPDATE statement 39using a Statement object 36

SQL queryexample 28

SQLException 92SQLquery

naming conventions 28SQLstate 92SSA 41SSAList 41

creating an 42DL/I data, accessing 43

SSAQualificationStatement 41SSAs 37, 41starting IMSTrace 96Statement object 36

retrieving 29status codes 93

CR 93mapping 91

STDENV DD statement 75STDERR DD statement 76STDOUT DD statement 75Stored Procedures

See DB2 environment 15String data type

boolean data type 32structures

nestedaccessing 55

sync pointfailure 93processor 93

SYSOUT parameter 75system requirements 3

CICS environment 13DB2 environment 15WebSphere for z/OS environment 8

SYSTSIN DD statement 76

TTIME data type 32TIMESTAMP data type 32TINYINT data type 32TMPREFIX 14TMSUFFIX 16tracing

IMS Java library routines 96

Index 117

tracing (continued)IMSTrace 96Trace statements, adding 97

transaction message input 46transactions

conversational 52local 3

turning on IMSTrace 96types

data, mapped to COBOL 33supported 32

UUPDATE statement 39URL (universal resource locator) 30USS (Unix System Services)

DLIModel utility, running 21

VVARCHAR data type 32

WWebSphere for z/OS

DRA startup table 9EJB, deploying 9, 11IMS JDBC Resource Adapter 9J2EE server 2ODBA 9

WebSphere for z/OS environmentaccessing IMS 9configuring 9DRA startup table 9installation verification 12overview 2restrictions 8setup 8system requirements 8

WHERE clause 38worker JVM 5

XXdfld statement 73XMI

creating 61metamodel 65

XOPEN SQLstate 92

ZZONEDECIMAL data type 32


Readers’ Comments — We’d Like to Hear from You

IMS Version 7IMS Java User’s Guide

Publication No. SC27-0832-02

Overall, how satisfied are you with the information in this book?

Very Satisfied Satisfied Neutral Dissatisfied Very DissatisfiedOverall satisfaction h h h h h

How satisfied are you that the information in this book is:

Very Satisfied Satisfied Neutral Dissatisfied Very DissatisfiedAccurate 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 anyway it believes appropriate without incurring any obligation to you.

Name Address

Company or Organization

Phone No.

Readers’ Comments — We’d Like to Hear from YouSC27-0832-02

SC27-0832-02

��Cut or FoldAlong Line

Cut or FoldAlong Line

Fold and Tape Please do not staple Fold and Tape

Fold and Tape Please do not staple Fold and Tape

NO POSTAGENECESSARYIF MAILED IN THEUNITED STATES

BUSINESS REPLY MAILFIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK

POSTAGE WILL BE PAID BY ADDRESSEE

IBM CorporationH150/090555 Bailey AvenueSan Jose, CA95141-9989

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

_

��

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

Documents