IMS Version 7 and Java Application Programming - IBM Redbooks

IMS Version 7 and Java
Application Programming
Learn to develop IMS Java applications
by following examples
Create Java control and
execution statements
Gain practical experience
in using Java
ibm.com/redbooks
Bill Arkins
Virgil Aguilar
Daniel Bourque
Giri Giritharan
Nancy Stein

International Technical Support Organization
IMS Version 7 and Java
Application Programming
February 2001
SG24-6123-00

Take Note!
Before using this information and the product it supports, be sure to read the general information in
Appendix K, “Special notices” on page 393.
First Edition (February 2001)
This edition applies to Version 7 of IMS, Program Number 5655-B01 for use with the OS/390 Operating
System.
Comments may be addressed to:
IBM Corporation, International Technical Support Organization
Dept. QXXE Building 80-E2
650 Harry Road
San Jose, California 95120-6099
When you send information to IBM, you grant IBM a non-exclusive right to use or distribute the
information in any way it believes appropriate without incurring any obligation to you.
© Copyright International Business Machines Corporation 2001. All rights reserved.
Note to U.S Government Users – Documentation related to restricted rights – Use, duplication or disclosure is
subject to restrictions set forth in GSA ADP Schedule Contract with IBM Corp.

Contents
Figures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xi
Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Preface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
The team that wrote this redbook. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xix
Part 1. IMS Java environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Chapter 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1 ET/390 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2 OS/390. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.3 IMS as an object server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3.1 Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3.2 IMS client for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.4 What is IMS Java? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.4.1 Other IMS Java considerations. . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.5 Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
1.5.1 Java environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
1.5.2 Java language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.5.3 Java for OS/390 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
1.5.4 High Performance Java compiler . . . . . . . . . . . . . . . . . . . . . . . . 17
1.5.5 Java tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.5.6 Class libraries and packages . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
1.5.7 VisualAge for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
1.5.8 VisualAge for Java tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
1.5.9 Java application structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
1.5.10 Access to hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Chapter 2. Environment customization. . . . . . . . . . . . . . . . . . . . . . . . . 23
2.1 Required software levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.1.1 NFS and FTP server tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
2.1.2 Java Development ToolKit (JDK) 1.1.8 . . . . . . . . . . . . . . . . . . . . 23
2.1.3 Visual Age for Java, Enterprise Edition for OS/390. . . . . . . . . . . 25
2.1.4 The HPJ compiler Installation on OS/390 . . . . . . . . . . . . . . . . . . 26
2.1.5 OS/390 UNIX System Services environment . . . . . . . . . . . . . . . 26
2.2 Workstation environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
2.2.1 Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
2.2.2 Required software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
2.2.3 NFS client. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
© Copyright IBM Corp. 2001 iii

Chapter 3. Building an IMS Java application . . . . . . . . . . . . . . . . . . . . 31
3.1 Overview of IMS application processing . . . . . . . . . . . . . . . . . . . . . . . 31
3.1.1 Message processing programs (MPPs) . . . . . . . . . . . . . . . . . . . 31
3.1.2 IMS Fast Path programs (IFPs) . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.1.3 Batch message processing programs (BMPs) . . . . . . . . . . . . . . 32
3.2 Message processing applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
3.2.1 Message queuing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
3.2.2 Reading and writing messages to the message queue in Java . . 33
3.3 Building an IMS Java application by example . . . . . . . . . . . . . . . . . . . 34
3.3.1 Introduction to the example environment . . . . . . . . . . . . . . . . . . 34
3.3.2 Building an IMS Java message processing application . . . . . . . . 35
Chapter 4. Conversational transactions . . . . . . . . . . . . . . . . . . . . . . . . 39
4.1 Defining an SPA message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
4.2 Conversational transaction sequence of events . . . . . . . . . . . . . . . . . 41
4.2.1 Defining subsequent input messages . . . . . . . . . . . . . . . . . . . . . 42
4.3 Using DLIConnection to access a database . . . . . . . . . . . . . . . . . . . . 42
4.3.1 DLIConnection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
4.3.2 DLISegment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.3.3 DLITypeInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.3.4 SSA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.3.5 SSAList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.3.6 SSAQualificationStatement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.3.7 DLIRecord . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.3.8 DLISegmentInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
4.3.9 DLIDatabaseView. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.4 Application programming using DLIConnection . . . . . . . . . . . . . . . . . 44
4.5 Subclassing DLISegment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
4.5.1 Coding messages with repeating structures . . . . . . . . . . . . . . . . 44
4.5.2 Accessing messages with repeating structures. . . . . . . . . . . . . . 46
4.6 Subclassing DLIDatabaseView. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
4.6.1 Creating a DLIConnection Object . . . . . . . . . . . . . . . . . . . . . . . . 46
4.6.2 Using SSAs to access DL/I information. . . . . . . . . . . . . . . . . . . . 47
Chapter 5. Accessing an IMS database. . . . . . . . . . . . . . . . . . . . . . . . . 49
5.1 Mapping an IMS database in Java classes . . . . . . . . . . . . . . . . . . . . . 49
5.1.1 IMS DB Database Definition (DBD). . . . . . . . . . . . . . . . . . . . . . . 49
5.1.2 Mapping the DBD to DLIDatabaseView . . . . . . . . . . . . . . . . . . . 50
5.1.3 Mapping the DBD to DLISegment . . . . . . . . . . . . . . . . . . . . . . . . 52
5.2 Using JDBC to access an IMS database . . . . . . . . . . . . . . . . . . . . . . 53
5.2.1 Classes and field names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
5.2.2 Writing a JDBC application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
5.3 Supported data types in IMS Java . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
iv IMS Version 7 and Java Application Programming

5.4 Supported SQL grammar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.4.1 SELECT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
5.4.2 FROM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
5.4.3 UPDATE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
5.4.4 DELETE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.4.5 INSERT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
5.4.6 How IMS Java has extended SQL . . . . . . . . . . . . . . . . . . . . . . . 65
5.4.7 Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
5.4.8 Prepared statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Part 2. Sample application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Chapter 6. IMSAuto application build and execute . . . . . . . . . . . . . . . 69
6.1 Testing IMS applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
6.2 “Nonvisual” IMS application development . . . . . . . . . . . . . . . . . . . . . . 71
6.2.1 Some TSO/E commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
6.3 ISHELL: Invoking UNIX System Services . . . . . . . . . . . . . . . . . . . . . . 73
6.4 OSHELL: Invoking BPXBATCH from TSO/E. . . . . . . . . . . . . . . . . . . . 79
6.5 OMVS: Invoking the UNIX System Services shell . . . . . . . . . . . . . . . . 81
6.6 BPXBATCH: Shell commands, shell scripts, or executable files . . . . . 83
6.7 OBROWSE and OEDIT: browsing and editing an HFS file . . . . . . . . . 86
6.8 OCOPY: Copying to another member or file . . . . . . . . . . . . . . . . . . . . 87
6.9 OGET, OGETX, OPUT, and OPUTX: Copying files and members . . . 88
6.10 Java Tools in UNIX System Services environment . . . . . . . . . . . . . . 88
6.10.1 javac command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
6.10.2 The hpj command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
6.11 Example of “nonvisual” application development . . . . . . . . . . . . . . 107
Chapter 7. VisualAge for Java IMS application development . . . . . . 119
7.1 IMS JAVA classes in VisualAge for Java Version 3.02 . . . . . . . . . . . 119
7.2 Writing, importing/exporting, and editing your program . . . . . . . . . . . 126
7.3 Exporting your program for execution . . . . . . . . . . . . . . . . . . . . . . . . 136
7.4 Preparing your program for execution . . . . . . . . . . . . . . . . . . . . . . . 142
7.5 Executing your Java program in IMS . . . . . . . . . . . . . . . . . . . . . . . . 148
Part 3. Debugging and problem determination. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Chapter 8. Diagnostic techniques . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
8.1 IMSTrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
8.1.1 Initiating IMSTracing. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
8.1.2 Setting up tracing for the IMS Java library routines. . . . . . . . . . 157
8.1.3 Adding trace statements to your application . . . . . . . . . . . . . . . 158
8.2 Writing your Java code with problem detection in mind. . . . . . . . . . . 160
v

8.2.1 Java sample tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
8.2.2 Trace started using a program argument . . . . . . . . . . . . . . . . . 160
8.2.3 Debugging trace method in each class . . . . . . . . . . . . . . . . . . . 160
8.2.4 Handling exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
8.3 Diagnosing problems with Java on OS/390 . . . . . . . . . . . . . . . . . . . 163
8.4 Diagnosing LE (Language Environment) messages and abends . . . 163
Chapter 9. Development limitations . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Part 4. Appendices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Appendix A. IMS Java package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
A.1 Contents of com.ibm.ims.application package . . . . . . . . . . . . . . . . . . . . 169
A.2 Class com.ibm.ims.application.IMSApplication. . . . . . . . . . . . . . . . . . . . 170
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
A.3 Class com.ibm.ims.application.IMSErrorMessages . . . . . . . . . . . . . . . . 171
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
A.4 Class com.ibm.ims.application.IMSFieldMessage . . . . . . . . . . . . . . . . . 172
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
A.5 Class com.ibm.ims.application.IMSMessageQueue. . . . . . . . . . . . . . . . 178
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179
A.6 Class com.ibm.ims.application.IMSTransaction . . . . . . . . . . . . . . . . . . . 181
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
A.7 Contents of com.ibm.ims.base package . . . . . . . . . . . . . . . . . . . . . . . . . 182
A.8 Class com.ibm.ims.base.AIB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
A.9 Class com.ibm.ims.base.AlternatePCB . . . . . . . . . . . . . . . . . . . . . . . . . 186
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
A.10 Class com.ibm.ims.base.DBPCB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
A.11 Class com.ibm.ims.base.DLIBaseSegment . . . . . . . . . . . . . . . . . . . . . 189
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
A.12 Class com.ibm.ims.base.DLITypeInfo . . . . . . . . . . . . . . . . . . . . . . . . . 211
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
vi IMS Version 7 and Java Application Programming

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
A.13 Class com.ibm.ims.base.DLITypeInfoList. . . . . . . . . . . . . . . . . . . . . . . 217
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
A.14 Class com.ibm.ims.base.IMSErrorMessages . . . . . . . . . . . . . . . . . . . . 219
Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
A.15 Class com.ibm.ims.base.IMSInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
A.16 Class com.ibm.ims.base.IMSTrace . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
A.17 Class com.ibm.ims.base.IOPCB. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232
A.18 Class com.ibm.ims.base.JavaToDLI. . . . . . . . . . . . . . . . . . . . . . . . . . . 233
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
A.19 Class com.ibm.ims.base.DLIJNICallbackException . . . . . . . . . . . . . . . 258
Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
A.20 Class com.ibm.ims.base.DLIWarning . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
A.21 Class com.ibm.ims.base.IMSException . . . . . . . . . . . . . . . . . . . . . . . . 259
Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
A.22 Contents of com.ibm.ims.db package. . . . . . . . . . . . . . . . . . . . . . . . . . 261
A.23 Class com.ibm.ims.db.DLIConnection . . . . . . . . . . . . . . . . . . . . . . . . . 262
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262
A.24 Class com.ibm.ims.db.DLIDatabaseView . . . . . . . . . . . . . . . . . . . . . . . 267
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
A.25 Class com.ibm.ims.db.DLIRecord. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
A.26 Class com.ibm.ims.db.DLISegment . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
A.27 Class com.ibm.ims.db.DLISegmentInfo . . . . . . . . . . . . . . . . . . . . . . . . 271
Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271
A.28 Class com.ibm.ims.db.DLIStatement . . . . . . . . . . . . . . . . . . . . . . . . . . 271
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
A.29 Class com.ibm.ims.db.IMSErrorMessages . . . . . . . . . . . . . . . . . . . . . . 279
Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
vii

Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
A.30 Class com.ibm.ims.db.SSA. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
A.31 Class com.ibm.ims.db.SSAList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
A.32 Class com.ibm.ims.db.SSAQualificationStatement . . . . . . . . . . . . . . . 294
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
A.33 Class com.ibm.ims.db.Token . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
A.34 Class com.ibm.ims.db.DLIException . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Constructors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299
Appendix B. Debugging and problem determination . . . . . . . . . . . . . . 301
B.1 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301
B.2 How exceptions map to DL/I status codes . . . . . . . . . . . . . . . . . . . . . . . 301
B.3 Sync point failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
B.4 “Try and catch” example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
Appendix C. IMS abend codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
C.1 Abends and pseudoabends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
C.2 Abends issued from IMS Java applications . . . . . . . . . . . . . . . . . . . . . . 305
C.2.1 ABENDU0118 - Commit failure . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
C.2.2 ABENDU0200 - Small I/O area defined . . . . . . . . . . . . . . . . . . . . . 305
C.2.3 ABENDU0462 - Get Unique was not issued . . . . . . . . . . . . . . . . . 306
C.2.4 ABENDU0475 - Batch run failure . . . . . . . . . . . . . . . . . . . . . . . . . . 306
C.2.5 ABENDU0778 - Rollback failure. . . . . . . . . . . . . . . . . . . . . . . . . . . 306
Appendix D. IMS Java tracing facilities . . . . . . . . . . . . . . . . . . . . . . . . . 307
D.1 IMSTrace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
D.2 Initiating IMSTracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307
D.3 Setting up tracing for the IMS Java library routines . . . . . . . . . . . . . . . . 307
D.4 Adding trace statements to your application. . . . . . . . . . . . . . . . . . . . . . 308
Appendix E. IVP application — Java source (Java to DLI version) . . 311
E.1 PhoneBookSegment class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
E.2 IVPDatabaseView class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
E.3 InputMessage class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
viii IMS Version 7 and Java Application Programming

E.4 OutputMessage class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
E.5 SPAMessage class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
E.6 Installation Verification Program (IVP) application . . . . . . . . . . . . . . . . . 316
Appendix F. IVP application — Java source (JDBC version) . . . . . . . 325
F.1 PhoneBookSegment class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
F.2 IVPDatabaseView class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
F.3 InputMessage class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
F.4 OutputMessage class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
F.5 SPAMessage class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
F.6 Installation Verification Program (IVP) application . . . . . . . . . . . . . . . . . 330
Appendix G. IVP application — COBOL source . . . . . . . . . . . . . . . . . . 339
G.1 IVP application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Appendix H. Installing the IVP Phone application . . . . . . . . . . . . . . . . 351
H.1 Installation verification process. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
Appendix I. Dealership sample application . . . . . . . . . . . . . . . . . . . . . . 357
I.1 Dealer class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
I.2 Model class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
I.3 Order class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
I.4 Sales class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
I.5 Stock class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
I.6 DealerDatabaseView class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
I.7 IMSAuto class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
I.8 InputMessage class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
I.9 OutputMessage class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
I.10 ErrorMessage class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
I.11 AcceptOrderInput class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
I.12 OrderAccepted class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
I.13 CancelOrderInput class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
I.14 Cancelled class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
I.15 FindACarInput class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
I.16 Carfound class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
I.17 ListModelsInput class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
I.18 ModelList class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
I.19 RecordASaleInput class. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
I.20 SalesRecord class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382
I.21 ShowModelDetailsInput class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
I.22 ModelDetails class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
ix

Appendix J. Options for the hpj command . . . . . . . . . . . . . . . . . . . . . . 385
Appendix K. Special notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393
Appendix L. Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
L.1 IBM Redbooks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
L.2 IBM Redbooks collections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
L.3 Other resources. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
L.4 Referenced Web sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
How to get IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
IBM Redbooks fax order form . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Abbreviations and acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411
IBM Redbooks review . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415
x IMS Version 7 and Java Application Programming

Figures
1. IMS Java development environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. IMS Java class library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. A simple class model for Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
4. Sample Java source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5. Java structure, components, and tools . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
6. Example of HPJ variables in /etc/.profile . . . . . . . . . . . . . . . . . . . . . . . . . . 27
7. JDK.profile file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
8. IMSJAVA.profile file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
9. NFS Network Access Suite connection customization . . . . . . . . . . . . . . . 29
10. Establishing NFS connections using net use in MS-DOS . . . . . . . . . . . . . 30
11. Database view of all segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
12. Example to define Input messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
13. Example to define Output messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
14. Example to Implement Main and doBegin(). . . . . . . . . . . . . . . . . . . . . . . . 37
15. SPA Message code (1) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
16. SPA Message code (2) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
17. SPA Message code (3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
18. Subsequent Input Message code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
19. Sample DLITypeInfo statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
20. The use of dotted notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
21. The use of field indexes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
22. Another example of dotted notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
23. Sample DLIConnection statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
24. Creating an SSALIST. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
25. Database view of all segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
26. IMS Database Definition (DBD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
27. Sample DBD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
28. Sample DLIDatabaseView. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
29. Dealer DBD extract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
30. Sample DLISegment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
31. JDBC Application code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
32. JDBC Connection code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
33. Example of a SELECT statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
34. Example of a FROM statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
35. FROM statement in Dealer code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
36. Example of an UPDATE statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
37. Example of a DELETE statement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
38. Example of WHERE and INSERT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
39. Example of an INSERT statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
40. IMS Java application development scenario . . . . . . . . . . . . . . . . . . . . . . . 69
© Copyright IBM Corp. 2001 xi

41. ISPF Command Shell panel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
42. ISHELL main screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
43. ISHELL Directory List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
44. ISHELL Select an Action panel for files . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
45. ISHELL Select an Action panel for directories . . . . . . . . . . . . . . . . . . . . . . 77
46. Display File Attributes option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
47. OSHELL ls -l input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
48. OSHELL ls -l output: Panel 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
49. OSHELL ls -l output: Panel 2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
50. OMVS startup panel. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
51. OMVS ls -l output: Panel 1. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
52. OMVS ls -l output: Panel 2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
53. BPXBATCH JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
54. Auto Dealer shell script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
55. The profile, profile.imsjava. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
56. The profile, profile.imsres4. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
57. First sample of javac output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
58. Another sample of javac output (part 1 of 2) . . . . . . . . . . . . . . . . . . . . . . . 95
59. Another sample of javac output (part 2 of 2) . . . . . . . . . . . . . . . . . . . . . . . 96
60. BPXBATCH JCL that executes shell script . . . . . . . . . . . . . . . . . . . . . . . . 97
61. Shell script to compile the auto dealer program. . . . . . . . . . . . . . . . . . . . . 98
62. STDERRL DD SYSOUT from BPXBATCH job (part 1 of 6) . . . . . . . . . . . 99
63. STDERRL DD SYSOUT from BPXBATCH job (part 2 of 6) . . . . . . . . . . 100
64. STDERRL DD SYSOUT from BPXBATCH job (part 3 of 6) . . . . . . . . . . 101
65. STDERRL DD SYSOUT from BPXBATCH job (part 4 of 6) . . . . . . . . . . 102
66. STDERRL DD SYSOUT from BPXBATCH job (part 5 of 6) . . . . . . . . . . 103
67. STDERRL DD SYSOUT from BPXBATCH job (part 6 of 6) . . . . . . . . . . 104
68. Example of hpj command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
69. javac compile and link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
70. BPXBATCH job . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
71. Shell Script to hpj compile and bind the IVP application . . . . . . . . . . . . . 110
72. Sample .profile.imsjava file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
73. Sample .profile.imsres4 file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
74. Sample .profile.hpj file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
75. STDOUTL file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
76. STDERRL File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
77. IMS Message Region STEPLIB Concatenation. . . . . . . . . . . . . . . . . . . . 116
78. IVP program input screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
79. IVP program output screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
80. VisualAge for Java startup screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
81. SmartGuide Import dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
82. SmartGuide (Import from a directory) dialog — application. . . . . . . . . . . 122
83. SmartGuide (Import from a directory) dialog — base . . . . . . . . . . . . . . . 123
xii IMS Version 7 and Java Application Programming

84. SmartGuide (Import from a directory) dialog — db . . . . . . . . . . . . . . . . . 124
85. IMS_Java_Class_Libraries listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
86. SmartGuide (Add Project dialog) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
87. SmartGuide (Add Package dialog) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
88. SmartGuide Create Class dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
89. The newly created class: IMSJavaPGM . . . . . . . . . . . . . . . . . . . . . . . . . 129
90. SmartGuide Create Method dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
91. Workbench showing newly added method . . . . . . . . . . . . . . . . . . . . . . . 131
92. Imported IMS Java classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
93. Workbench showing expansion of classes . . . . . . . . . . . . . . . . . . . . . . . 133
94. Workbench showing modifiable source code. . . . . . . . . . . . . . . . . . . . . . 134
95. Workbench showing a method with an error . . . . . . . . . . . . . . . . . . . . . . 135
96. Javadoc option screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
97. ET/390 Properties for object Dealership . . . . . . . . . . . . . . . . . . . . . . . . . 137
98. ET/390 Properties for object Dealership (Bind Options) . . . . . . . . . . . . . 138
99. Workbench (Administrator) menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
100.SmartGuide Export dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
101.SmartGuide Export to a directory dialog . . . . . . . . . . . . . . . . . . . . . . . . . 141
102.Duplicate name error message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
103.BPXBATCH job to execute HPJ-only shell script . . . . . . . . . . . . . . . . . . 143
104./u/imsres4/Dealerhpj.sh.standalone -— HPJ-only shell script. . . . . . . . . 144
105.u/imsres4/Dealerscript.ver3 — script to execute 2 other scripts . . . . . . . 145
106.u/imsres4/Dealerjavac.sh.ver3 — javac compile script . . . . . . . . . . . . . . 146
107.u/imsres4/Dealerhpj.sh.ver3 - HPJ binder script . . . . . . . . . . . . . . . . . . . 147
108.Stage1 Gen input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
109.DB2 Gen input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
110.PSB Gen input. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
111.IMS message region STEPLIB concatenation . . . . . . . . . . . . . . . . . . . . 151
112.A typical IMSFieldMessage subclass . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
113.Example of how to access the fields in subclass InputMessage. . . . . . . 173
114.Example of coding messages that have the same field in common . . 175
115.Example of Message reading logic . . . . . . . . . . . . . . . . . . . . . . . . . . 176
116.Example of retrieving messages using a while loop . . . . . . . . . . . . . . . . 178
117.Example defining an OutputModel message. . . . . . . . . . . . . . . . . . . . . . 218
118.Using System.out for trace output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
119.Example: A typical DLIDatabaseView subclass . . . . . . . . . . . . . . . . . . . 268
120.Example: A typical DLISegment subclass. . . . . . . . . . . . . . . . . . . . . . . . 270
121.DLIConnection list . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
122.Status code call exception example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
123.Example of “try and catch” methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304
124.IMS Java profile sample . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351
125.HPJ command to create executable load . . . . . . . . . . . . . . . . . . . . . . . . 351
126.Sample MVS BPXBATCH JCL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352
xiii

127.Sample IVP BPXBATCH Script. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
128.Sample IMS Java class library and HPJ class libraries. . . . . . . . . . . . . . 354
129.IVTCC input screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
130.IVTCC DISPLAY query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
131.IVTCC DISPLAY output query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
xiv IMS Version 7 and Java Application Programming

Tables
1. Supported data types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
2. Available get methods for data types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
3. Supported SQL keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
4. References to source code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
5. Status code, reason and return code. . . . . . . . . . . . . . . . . . . . . . . . . . . . 303
6. Options for the hpj command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
© Copyright IBM Corp. 2001 xv

xvi IMS Version 7 and Java Application Programming

Preface
This IBM Redbook is intended for customers who wish to exploit the Java
language support provided by IMS Version 7.1. Its prime audience are IMS
and Java application programmers, who can now use Java to develop IMS
application transactions, and IMS system programmers, who support IMS
applications development. This book will be helpful to any organization that is
interested in user developed S/390 Java applications, especially to access
IMS databases by using Java application programming.
As Java coding skills have become more readily available in the IT
employment marketplace, application development with Java has become
more and more the de facto coding standard. This book expands upon the
IMS Java User’s Guide, SC27-0832-00, and provides a practical reference for
developing an IMS application transaction written in Java.
This book assumes a certain level of knowledge of IMS, Java, and UNIX.
We start by overviewing the base concepts of the Java environment and
introduce new terminology. We then provide information about the S/390
software and hardware requirements which enable Java on the Enterprise
platform, and we describe how to download, install, and configure the Java
related application development environment for your workstation, IMS/ESA,
and OS/390.
We discuss two IMS applications that were developed within IBM, using the
Java API to IMS. The Telephone Directory IVP application uses the Java
Native DL/I interface, and the IMS Auto Dealership application employs the
JDBC interface from Java to IMS. We also provide guidance on debugging,
problem determination, and some of the development limitations.
The team that wrote this redbook
This redbook was produced by a team of specialists from around the world
working at the International Technical Support Organization San Jose Center.
Bill Arkins is an IMS Product Specialist with the International Technical
Support Organization, San Jose Center. He writes extensively and teaches
IBM classes worldwide in the areas of IMS performance, Parallel Sysplex,
and S/390 large buffer pool performance. Before joining the ITSO in July
2000, Bill worked in the IMS Technical Support, IMS QPP, and IMS
Performance groups. Bill also spent 5 years in Europe on assignment and
has been a regular presenter at SHARE, GUIDE, CMG, and IMS Technical
conferences.
© Copyright IBM Corp. 2001 xvii

Virgil Aguilar is a Staff Software Engineer with the IBM Silicon Valley
Laboratory in San Jose, CA. He has been working as an IMS Transaction
Manager Level 2 for the past 5 years. His areas of specialization are OTMA,
APPC, security and IMS e-connectors. Before joining IBM, he worked as an
IMS Applications Programmer, Systems Programmer, and Database
Administrator in the banking, telephony, and electric utility industries for 10
years. He holds a Bachelor’s degree in Mathematics from University of the
Philippines.
Daniel Bourque is an IMS Product Specialist with the IBM Silicon Valley
Laboratory in San Jose, CA. He holds a degree in Management Information
Science and Finance from the University of Florida. Daniel has 4 years of
experience in the IT industry and specializes in System/390 database
management and connectivity.
Giri Giritharan is an IMS Systems Programmer with IBM Global Services,
Australia. He has worked in financial institutions before joining IBM in 1989.
He has over 13 years of experience in IT, of which 6 years have been with
IMS. His areas of expertise include installation, maintenance, performance
tuning, and problem diagnosis.
Nancy Stein is a Senior Software Engineer with the IBM Silicon Valley
Laboratory in San Jose, CA. Before joining the IBM Software Group’s IMS
Product Services/Advocacy team in 1998, she worked as an IMS Applications
Developer, IMS Systems Programmer, MVS Systems Programmer, and
OS/390 Technical Support Principal for a major telecommunications
company. She has over 23 years experience developing, architecting,
debugging, and tuning IMS systems and applications.
Thanks to the following people for their invaluable contributions to this
project:
Ken Blackman
IBM IMS Advanced Technical Support, Dallas Systems Center, Dallas, TX
Kyle Charlet
IBM IMS Development, Silicon Valley Laboratory, San Jose, CA
Rich Conway
International Technical Support Organization, Poughkeepsie, NY
Bach Doan
IBM IMS Development, Silicon Valley Laboratory, San Jose, CA
xviii IMS Version 7 and Java Application Programming

Comments welcome
Eugene Dong
IBM IMS Development, Silicon Valley Laboratory, San Jose, CA
Scott Gieselman
IBM IMS Development, Silicon Valley Laboratory, San Jose, CA
Vasilis Karras
International Technical Support Organization, Poughkeepsie, NY
Yvonne Lyon
International Technical Support Organization, San Jose, CA
Bob Love
IBM IMS Development, Silicon Valley Laboratory, San Jose, CA
John Shelton
IBM IMS Development, Silicon Valley Laboratory, San Jose, CA
Your comments are important to us!
We want our Redbooks to be as helpful as possible. Please send us your
comments about this or other Redbooks in one of the following ways:
Fax the evaluation form found in “IBM Redbooks review” on page 415 to
the fax number shown on the form.
Use the online evaluation form found at ibm.com/redbooks
Send your comments in an Internet note to redbook@us.ibm.com
xix

xx IMS Version 7 and Java Application Programming

Part 1. IMS Java environment
This part of the book describes the IMS Java environment.
It contains the following chapters:
Chapter 1, “Introduction” on page 3.
Chapter 2, “Environment customization” on page 23
Chapter 3, “Building an IMS Java application” on page 31
Chapter 4, “Conversational transactions” on page 39
Chapter 5, “Accessing an IMS database” on page 49
© Copyright IBM Corp. 2001 1

2 IMS Version 7 and Java Application Programming

Chapter 1. Introduction
In this chapter we familiarize you with the basic concepts of and
developments in object-oriented (OO) technology in relation to the OS/390
and IMS. The main topics covered are the positioning of OS/390, IMS and
Java, and the use of Java in an IMS environment.
This book contains the following information on IMS Java:
Information on user setup, with compile and run time options and an
example shell script to set your classpath default.
The basics of how an application works, with an overview of IMS
application processing, information on message queueing, and a car
dealership application example that is used throughout this book.
How to access an IMS database with information on mapping databases in
Java classes, defining IMS databases and DBDs, JDBC access of IMS
databases, and supported SQL grammar.
Advanced application topics, including:
- Conversational transactions
- Multi-segment messages
- Installation verification
- DLIConnection access of databases
- Application programming with DLIConnection
- Subclassing IMSSegment
- Providing an array
- Creating a DLIConnection object
- SSA use to access DL/I information
- DLIDatabaseView connection example
- JavaToDLI example
Debugging and determining problem causes, including information on:
exceptions, sync point failure, abends and dumps, and IMSTrace.
Appendixes containing a complete sample program, IVP database view
samples, and an IVP.
An index of terms.
These concepts are illustrated in Figure 1 and Figure 2.
© Copyright IBM Corp. 2000 3

VisualAge for Java,
Enterprise Edition
Edit/Compile
Browse
Version Control
Error Feedback
Local
Debugger
Remote
Debugger
Profiler
J
P
O
R
T
Figure 1. IMS Java development environment
Export
Java
Bytecode
4 IMS Version 7 and Java Application Programming
IMS
Java
High
Performance
Compiler
PC Server
320
Executable
Run on
OS/390
Trace
OS/390

SSAQualificationStatement
SSAList
SSA
DLIConnection
DLISegment
DLISegmentInfo
DLIDatabaseView
DLIRecord
Implementation of java.sql
Figure 2. IMS Java class library
1.1 ET/390
Uses JNI (java
native interface)
to access C
Java Class Library
A java program uses the APIs that are provided
application Package classes to
- initialize and begin the program
- get the input message from the message queue
- put the output message on the message queue
- commit
JDBC interface or db Package classes to
- access the IMS databases
JDBC interface
db Package
application Package
base Package
CEETDLI Interface for C Language
IMS DB IMS System IMS TM
IMSApplication
IMSFieldMessage
IMSMessageQueue
IMSTransaction
AIB
AlternatePCB
DBPCB
DLIBaseSegment
DLITypeInfo
IOPCB
IMSException
IMSInfo
JavaToDLI
VisualAge for Java, Enterprise Edition for OS/390 includes the Enterprise
Toolkit for OS/390 (ET/390) which allows you to quickly and easily develop
enterprise applications in Java. If you want to improve the performance of
your Java code for the OS/390 environment, you can use ET/390 to bind your
Java bytecode into optimized object code to run under OS/390 UNIX System
Services. The fully bound object code runs as an executable or DLL in the
OS/390 shell.
ET/390 not only provides additional functionality, but it also supplies a
comprehensive suite of development tools. ET/390 extends the VisualAge for
Java tool set by including an interactive debugger and the Performance
Chapter 1. Introduction 5

1.2 OS/390
Analyzer. The debugger lets you debug your Java bytecode as it runs in
OS/390.
The Performance Analyzer complements the debugger by allowing you to
take a trace of the Java object code as it runs in the OS/390 shell. You can
use graphical and textual diagrams at the workstation to analyze the
complete history of method calls captured in the trace file and identify parts of
the Java code that you may want to tune.
Today, OS/390 combines the robustness of historic MVS and
UNIX-95-compliant UNIX Systems Services in one operating system.
Some of the unique classic strengths of S/390 are:
Flexibility OS/390 is open and allows you to integrate data and
applications with its environment. Also, application porting
to OS/390 is easy because of the presence of the UNIX
Systems Services. This set of services was known as
OpenEdition/MVS in releases of OS/390 prior to 2.5. The
ability to use the processor to its maximum capability is
designed into OS/390. Thus you can purchase systems to
run your aggregate workload and manage the peaks with
the same processor capacity, instead of buying capacity to
match your peak workloads and having it under utilized the
rest of the time. OS/390, through its Workload Manager
(WLM), can manage both traditional work and new workload
types such as Java, according to the business priorities you
set.
Data Approximately 70% of the data of mission-critical
applications worldwide resides on S/390. A wide range of
features and products support an absolutely secure
environment for storing your data with integrity.
Performance High-volume transaction processing and heavy batch
processes are common on S/390. S/390 is very efficient in
managing its use of hardware and software resources.
Availability S/390 availability is the best in the industry. It can provide
continuous availability so that your applications are
available to your users and customers whenever they need
them.
6 IMS Version 7 and Java Application Programming

Manageability One S/390 server can serve thousands of users anywhere
in the world. One centrally located department of IS staff is
sufficient to manage and supply information services
throughout the world. Because changes in data or
applications have to be made only once at one place, they
become active at the same time for all users.
Scalability It is possible to serve your data and/or applications on S/390
to thousands or, when serving the Internet, even millions of
new users without necessarily having to replicate your
servers.
Security OS/390, and the S/390 hardware, have been architected for
more than 25 years to isolate applications and subsystems
from one another and to provide user authentication and
access control. Java programs and applications that run on
S/390 benefit from this extended security model as well as
the standard, built-in, security of the Java environment.
OS/390 has evolved to a fully open operating system that supports:
Internet Web serving
High security and integrity required for electronic commerce
Distributed object-oriented application architectures
This support, combined with the classic strengths of OS/390, makes it an
excellent operating system for your current and future mission-critical
applications and data.
1.3 IMS as an object server
The transaction processing strengths of IMS in an enterprise computing
environment are appreciated and exploited worldwide. IMS has always
provided a robust transaction processing environment that:
Allows creation of transactions with atomicity, consistency, isolation, and
durability (ACID) properties.
Allows transactions to run under all sorts of conditions.
Provides continuous operation and high availability with (more recently)
sysplex support, data sharing, and the removal of single points of failure.
1.3.1 Background
IMS is unique in a number of ways, making this environment significantly
easier for IMS to move into and thus rapidly provide solutions:
Chapter 1. Introduction 7

1. IMS is proprietary to the S/390 and has been designed to easily exploit,
integrate with, and utilize any new S/390 hardware or software function
immediately. This includes the ability for IMS to take immediate
advantage, not only of S/390 storage, communication, and data
management facilities, provided by the operating system, but also of
any Sysplex, OpenEdition, Recoverable Resource Management
Services for distributed coordinated commit, and WebSphere
Application Server functions, for example, as well.
2. IMS has provided an extremely easy application model, structured to be
device and environment independent. Thus, there are no hidden
dependencies of IMS applications on the environment. For example,
any address space and task structure changes would not affect the IMS
application as they might under other transaction systems.
3. As a message-driven queued system, the IMS application is in most all
cases structured to be independent of message delivery timing and of
what has gone on before. This makes IMS more robust, reliable, and
easier to recover from problems. Because of the way the IMS
application has thus had to be written, concurrency issues of other
transaction management systems do not arise in IMS. This stateless
condition, common to most IMS applications, is also how Java and the
Internet are structured, making IMS a natural application server for this
environment.
4. The IMS programming model in scheduling an application is very
powerful, providing applications, for example, the ability to emulate both
synchronous or asynchronous communication and make either work
very well.
5. IMS is, in fact, an object manager, with applications encapsulating data
into IMS transaction objects and where data objects can be stored as
IMS database segments. This makes object programming a natural
transition for the IMS programming environment.
6. IMS has been providing a broad base of connectivity interfaces, for both
SNA and TCP/IP network access and for subsystem access. Recent
subsystem access facilities are the IMS V7 Open Transaction Manager
Access (OTMA) facility and the new IMS V7 Open Database Access
(ODBA) facility.
1.3.2 IMS client for Java
IMS is exploiting the latest programming technologies for the Internet. This
includes Java, which enables interactive and multimedia applications in a
simplified fashion. With Java, users can transparently download and
8 IMS Version 7 and Java Application Programming

1.4 What is IMS Java?
seamlessly run applications. This may be something as simple as animating
the title of the HTML file, or something more complex, such as automatically
retrieving desired information from various sites around the Internet and
manipulating it.
Java is multithreaded and interpreted. It can thus be widely used and is
platform independent. Initially provided here for this environment is the IMS
Client for Java, which consists of application and applet code for preparing a
Java program to access IMS applications and data, and a user exit to
translate the message into the format required by the IMS Version 7 Open
Transaction Manager Access (OTMA) interface. This code uses the IMS
Connect to access IMS.
IBM has ported Java to the S/390, providing the popular Java run-time
environment from PCs to S/390s. Today the IBM Domino Go Webserver for
OS/390 is able to host Java applets for downloading to Java-enabled Web
browsers. And the IMS Client for Java provides an applet for this purpose.
Recent IMS Client for Java V2.1 enhancements provide conversational,
security, and capacity/usability enhancements.
IMS Java allows IMS shops to take advantage of the growing pool of Java
trained programmers. It extends existing IMS transactions to e-business,
uses Java with high-performance server solutions, and reduces the
complexity of IMS application development.
IMS Java was developed to provide an application programming interface
(API) that is usable by experienced Java programmers, and to provide an API
that can later be supported with code generation tools, such as those found in
VisualAge for Java. IMS Java provides you with the ability to develop new
applications more easily. IMS Java also provides Java programmers with
complete access to necessary IMS services.
IMS Java is delivered in a layered set of class libraries providing high-level
classes that focus strongly on ease-of-use, and lower-level classes that
provide complete access to IMS services and serve as the implementation
vehicle for the higher-level classes.
IMS Java on the OS/390 platform supports:
High Performance Java (HPJ) compiled Java applications executing in all
IMS dependent regions (MPP, IFP, and BMP), but not in a JVM.
Chapter 1. Introduction 9

Java class libraries that support the development of applications within
visual development environments (like VisualAge for Java) to access the
IMS message queue and to DL/I data on OS/390.
Access to DB2 data on OS/390 through the use of JDBC and SQLJ within
a Java application. See your DB2 documentation for further explanation.
Java Database Connectivity (JDBC) access to DL/I data.
Alternate PCB program switching. IMS Java allows programs to use the
alternate PCB to send messages to another terminal or program, including
a COBOL program.
Conversational transactions and non-conversational transactions.
Fast Path databases. There is no limitation on the use of DEDB
databases.
Full-Function databases.
Multi-segment messages. There is no limitation to the use of
multi-segment and single-segment messages.
Message formatting services (MFS) are available by passing the MOD
names to IMS.
Secondary indexes.
Logical relationships.
High availability large databases (HALDBs).
HIDAM.
1.4.1 Other IMS Java considerations
1.5 Java
IMS Java programs must be single-threaded. IMS Java only supports the AIB
interface, therefore the database PCBs in your PSBGEN must be named.
IMS Java applications can only call other language applications through Java
native interface (JNI) that are POSIX(ON), therefore you cannot call COBOL
functions. In addition, you cannot currently invoke a Java program from a
COBOL program.
Java is an OO programming language and execution environment that offers
significant new opportunities for software development, interoperability, and
portable execution. In this section we introduce the technology, explain the
basics, and position Java and Java technology. Java started its life in 1991 as
part of a Sun Microsystems project called OAK, a software environment
10 IMS Version 7 and Java Application Programming

(“virtual machine”) and programming language aimed at cable television
“set-top” boxes. For various reasons the name OAK was dropped, and the
name Java was adopted before the first release of the resulting technology.
To meet the objectives of this project, Java was designed from the outset to
be small, portable, fast, and safe. These characteristics would later prove to
be an essential part of Java's success, as they made Java an ideal language
for the explosion in growth of the Web and the Internet.
As part of this explosive growth, Sun released a Web browser called HotJava.
To implement the browser, Sun licensed the source code for the HotJava
environment, the Java Virtual Machine (JVM). This meant that the JVM and
Java language were soon available on other UNIX systems, and shortly
afterward on OS/2 and Microsoft Windows.
It did not take long for technologists to realize the potential advantages
offered by the JVM and its portable bytecode: rapid takeup followed and
ushered in a new generation of Internet programming.
Today, Java can be deployed in applications, in full executable programs that
perform functions similar to applications written in traditional languages, and
in applets, which are small reusable extensions to a Web browser. The
extensions are restricted in what they can do, and the environment they run in
is completely secured by the Web browser. A Java program can also run in a
Web server environment as a servlet, thus extending the function provided by
a Web server. IBM provides a plug-in, WebSphere Application Server, that
allows Web servers to run servlets. WebSphere Application Server is not a
prerequisite for IMS support of the Java language or of a CORBA client.
The full impact of Java will be seen over time. However, its impact to date
should not be underestimated. Java has been and continues to be adopted
by many businesses and technology companies both large and small.
The Java platform is a way of computing, based on the idea that the same
software should run on many different kinds of computers and devices. With
the Java technology, you can use the same application from any kind of
machine — a PC, a Macintosh computer, a network computer, or even new
technologies like Internet screen phones.
Java technology components do not care what kind of computer, device or
operating system they run on. They just work on any kind of compatible
device that supports the Java platform. Java technology is widely regarded as
revolutionary, because it is designed to let computers and devices
communicate with one another much more easily than ever before.
Chapter 1. Introduction 11

Java is a simple, robust, object-oriented, platform-independent,
multithreaded, dynamic, general-purpose programming environment for
creating applications for the Internet and Intranet. The open,
platform-independent, object-oriented nature of Java technology means
developers can solve the problem of integrating with existing computers that
previously would have seemed unthinkably complex.
With Java technology, the Internet and private networks become your
computing environment. For example, users can securely access their
personal information and applications when they are far away from the office
by using any computer that is connected to the Internet.
1.5.1 Java environment
Java, a programming language developed by Sun Microsystems, is
object-oriented, distributed, interpreted, architecture-neutral, and portable.
Java can be used to create downloadable program fragments, so-called
applets, that augment the functionality of a Java-capable browser such as
Netscape Navigator. Additionally, Java can be run as a stand-alone
application, without the use of a Browser, in a Java virtual machine.
Java originated as part of a research project to develop advanced software
for a wide variety of network devices and embedded systems. The goal was
to develop a small, reliable, portable, distributed, real-time operating
platform. The result is a language platform that has proven ideal for
developing secure, distributed, network-based end-user applications in
environments ranging from network-embedded devices to the World-Wide
Web and the desktop.
The design requirements of Java are driven by the nature of the computing
environments in which software must be deployed. The massive growth of the
Internet and the World-Wide Web lead to a completely new way of looking at
development and distribution of software. To live in the world of electronic
commerce and distribution, Java must enable the development of secure,
high performance, and highly robust applications on multiple platforms in
heterogeneous, distributed networks.
Java is designed to meet the challenges of application development in the
context of heterogeneous, network-wide distributed environments.
Paramount among these challenges is secure delivery of applications that
consume the minimum of system resources, can run on any hardware and
software platform, and can be extended dynamically.
12 IMS Version 7 and Java Application Programming

Operating on multiple platforms invalidates the traditional schemes of binary
distribution, release, upgrade, patch, and so on. Java must be architecture
neutral, portable, and dynamically adaptable. The Java system meets these
needs. It can be easily programmed by most developers. Current developers
can easily learn Java. It is object-oriented to take advantage of modern
software development methodologies and it fits into distributed client-server
applications. Multithreaded for high performance in applications that need to
perform multiple concurrent activities, such as multimedia, Java also is
interpreted for maximum portability and dynamic capabilities.
1.5.2 Java language
Java is a high-level language, similar to C and C++. Java is claimed to be
(relatively) simple when compared to C++, as many of the more error-prone
aspects of C++ have been eliminated. For example, Java has no
preprocessor, pointers, or goto, only limited casting, and automatic garbage
collection.
Java is object-oriented, but without all the complications. It has a single
inheritance model, simple data types, and code that is organized into classes.
These classes provide an excellent way of packaging functions. It is
object-oriented from the ground up and meshes well with the needs of
client-server and distributed software. Benefits of object technology are
rapidly becoming realized as more organizations move their applications to
the distributed client-server model. An important characteristic that
distinguishes objects from ordinary procedures or functions is that an object
can have a lifetime greater than that of the object that created it. This aspect
of objects is subtle and mostly overlooked.
In the distributed client-server world, you now have the potential for objects to
be created in one place, passed around networks, and stored elsewhere,
possibly in databases, to be retrieved for future work. As an object-oriented
language, Java draws on the best concepts and features of previous
object-oriented languages, primarily Eiffel, SmallTalk, Objective C, and C++.
Java goes beyond C++ in both extending the object model and removing the
major complexities of C++. With the exception of its primitive data types,
everything in Java is an object, and even the primitive types can be
encapsulated within objects if the need arises.
Interfaces to the objects are abstract classes. Classes can implement
multiple interfaces. The interfaces are similar to CORBA interface definition
language (IDL) interfaces. A number of products and tools are available,
including IBM's Component Broker, that can bridge between Java and
CORBA.
Chapter 1. Introduction 13

As a language, Java is statically typed, and most type checking is done at
compile time. However, run-time checks such as array bounds, are still
required. A key function of Java is that numeric precision is defined with the
IEEE floating point notation, which ensures the same results everywhere for
mathematical calculations. Figure 3 illustrates a simple Java class model.
Java has a simple class hierarchy, and a single inheritance model. This
example shows two types of classes: Vehicle and Building. Both classes can
inherit from the class above. Classes further down in the hierarchy can inherit
from either the Vehicle or the Building class but not both. Other object-based
technologies also have single inheritance, and some more complex
technologies have multiple inheritance, where a class could inherit from both
the Vehicle and Building class.
Figure 3. A simple class model for Java
Figure 4 shows some Java source code (the typical "Hello World" program)
and the basic structure and elements of a Java application. It begins with
block documentation comments that are started with /** and end with */. If
this program were processed by the Java-Javadoc utility, a standard part of
the Java Development Kit (JDK), these comments, along with the structure of
the program, its methods, and other documentation comments, would be
automatically included in a documentation file in HTML format.
A second form of comment can also be seen in the program: // display
string. This is a private comment and will not be included in the HTML file
that Javadoc produces. Java also supports a third style of comment: the
classical C comment starting with /* and ending with */. These are also
private and are not included in Javadoc HTML files. Some sample Java
source code is shown in Figure 4.
14 IMS Version 7 and Java Application Programming

**
*HelloWorldApp class implements an application that simply
*displays "Hello World" to the standard output device.
*/
public class HelloWorldApp {
public static void main(String[] args) {
System.out.println("Hello World!"); //display string
}
}
Figure 4. Sample Java source code
After the documentation comment you can see the name of the class defined:
HelloWorldApp. This part of the program gives us important information, such
as whether this is an application, an applet, or a servlet. In this case the
sample program is an application — it has a main() construct in its source
code — and it can be executed from a command line.
The name of the class is case sensitive and must match the name of the file.
The file type is .java, making the full file name HelloWorldApp.java. The file
name, for example javac HelloWorldApp.java, is used when you compile the
program. A Java program is compiled into a .class file. The class name
without its file type of .class, for example java HelloWorldApp, is used when
you run the program.
The next part of the program defines the properties of the Java program or
class. In this case it is a public class that can be called by any other class.
Our sample program returns no data, and it takes as input a character string
of command line arguments.
Finally our sample program performs its function: in this case to print out
"Hello World" by creating an instance of a Java class. If you are only familiar
with procedural programming, you could think of this as a call to a
system-provided function. In reality it is very different, but that is beyond the
scope of this introduction.
The source code shown in Figure 4 would be compiled into machine
independent bytecode with the Java compiler, javac. The bytecode is
conceptually similar to an object deck in S/390 terms. It is executable but still
needs to be link-edited.
Java bytecode is dynamically linked; that is, functions external to the program
are located and loaded at runtime rather than being statically bound to the
Java bytecode. Thus functions can be loaded on demand over the network
when needed, with unused code never loaded. If the Java program is an
Chapter 1. Introduction 15

application or servlet, it can still be dynamically linked by loading classes over
a network-based file system such as network file system (NFS), distributed
file system (DFS), or Andrew file system (AFS). Typically, however all the
required classes would be installed locally for applications and servlets.
Once loaded and linked, Java bytecodes are ready for execution. Originally
Java bytecode was always interpreted, that is, translated into native
instructions. However, by default, almost all JVMs include a just-in-time (JIT)
compiler. The JIT uses a number of techniques to precompile or cache and
reuse native instructions. A JIT provides significant performance advantages,
as demonstrated by the improved JIT releases of the OS/390 JDK 1.1.4 in
April 1998, and in the 1.1.6 JDK in October 1998.
Because Java bytecode is in a machine-independent, architecture-neutral
format, it can be run on any system with a standard Java implementation. An
extensive library of underlying classes or functions can be used to do
everything from graphics to network communication. Because these classes
are Java bytecode, they too are machine-independent.
1.5.3 Java for OS/390
The implementation of Java on OS/39O started in 1996 with a port of the AIX
JDK 1.0.2 to the OS/390 UNIX Systems Services. The AIX JDK is based on
licensed source code from Sun Microsystems.
The OS/390 JVM maps Java threads onto native OS/390 threads. All Java
threads are run on an OS/390 task control block (TCB). This makes all Java
threads truly multithreaded and preemptively multitasked and
multiprocessor-capable. Java components that implement multiple threads
can exploit the S/390 architecture without knowledge of or programming for
the underlying OS/390 operating system.
In 1997, the JDK 1.1.1 for OS/390 was released and was the first fully
supported implementation of Java on OS/390. JDK 1.1.1 included a JIT
compiler and a number of other improvements. January 1998 saw the release
of an updated JDK 1.1.1 with a number of defects fixed and an updated JIT
with significantly improved performance.
The next significant update was with OS/390 JDK 1.1.4, which included all
the previous enhancements, plus a new Java garbage collection model. In
Java, programmers do not allocate and free memory. Memory is allocated by
the JVM when needed, and then, in the standard Java implementation, the
JVM periodically suspends all running threads and reclaims memory that is
no longer in use.
16 IMS Version 7 and Java Application Programming

In a server environment, to make systems both scalable and efficient and to
provide a predictable response time, the OS/390 JVM now reclaims memory
in real time without the suspension of executing threads. From a
programming perspective, this change remains completely compatible and
does not require any additional programming.
1.5.4 High Performance Java compiler
Most JVMs contain a JIT compiler to improve execution performance. JIT
compilers turn Java bytecode into native object code "on-the-fly", as it is
loaded into the JVM. The JVM then executes the generated object code
directly, instead of interpreting bytecodes. Because this translation is done for
each execution phase, the requirement for reasonable compilation speed
constrains the amount of optimization that a JIT compiler can perform.
VisualAge for Java, Enterprise Edition for OS/390 contains a new component,
Enterprise Toolkit for OS/390 (ET/390). This component introduces an
optimizing native code compiler that statically compiles Java bytecode
directly into native object code. This compiler is called the High Performance
Java (HPJ) compiler. Unlike with the JIT compilation, the ET/390 static
compilation occurs only once, before execution time. The HPJ compiler also
fully binds the code into an executable or dynamic link library (DLL) that can
be run in the OS/390 shell or under IMS.
1.5.5 Java tools
One of the strengths of Java is the set of standard tools and class libraries
that are included in every JDK. The tools include the following:
javac The Java compiler. This is actually a Java program that
translates Java source code programs into Java bytecode.
jdb The Java debugger
javah Generates header files for C or C++ programs to
interoperate with and call Java programs or objects.
javakey Can be used to generate security keys for use with Java
and Java programs.
javap The Java disassembler. It takes Java bytecode and
produces pseudo Java source code. The source code
contains enough information for a programmer to be able
to understand the structure, classes, and methods within
the bytecode. However, the source code needs extensive
reprogramming before it can be recompiled and used.
Chapter 1. Introduction 17

javadoc Takes a Java source code program and produces
documentation in the form of HTML files. The
documentation contains class structures and methods.
Where Java documentation comments are included in the
source code they will be included in the HTML file at the
correct point, class, or method definition.
rmic/rmregistry A pair of tools to build and locate Java objects in a
networked or stand-alone environment. These are a set of
basic services that reduce the need to hard code locations
in program source code.
appletviewer Is used to test and display the output from Java applets. It
can be used on OS/390 with an X-terminal or X-capable
server to handle the actual display.
In addition to these there are a number of other standard tools and utilities.
1.5.6 Class libraries and packages
Like the standard set of tools available in every JDK, one of the big
advantages of Java is the built-in, standard class or run-time libraries and
packages available in every JDK. These include:
java.lang Essential Java classes, implicitly imported. Contains
object, string, number, exception, error, and other
java.io Stream-based input/output file system.
java.util Utility classes, date, random, dictionary hashtable, vector,
enumeration and other
java.net Networking, sockets, addresses, uniform resource
locators (URLs)
java.awt Abstract Windowing Toolkit (AWT), cross-platform
graphical user interface (GUI)
java.applet Support for applets
Packages often contain one or more classes. For example, java.lang
contains java.lang.Thread and .System. These were the standard class
packages in Java JDK 1.1. Others have been defined and architected for
inclusion in Java JDK 1.2 including a replacement for the java.awt, java.jfc, a
richer cross-platform GUI, and java.servlet, which is currently available only
in the Java Servlet Development Toolkit, as well as many others.
Figure 5 shows the structure, relationships, and interoperability of the various
Java components, the operating system, and the hardware.
18 IMS Version 7 and Java Application Programming

1.5.7 VisualAge for Java
Figure 5. Java structure, components, and tools
In 1997, the focus of Java development changed somewhat to encompass
enterprise computing. Today you need a robust development environment to
create large and complex applications. You need an environment with code
management, powerful searching and browsing, GUI building, and JavaBean
creation and manipulation capabilities. You need an environment that helps
you think in terms of objects.
VisualAge for Java is an integrated, visual development environment that
supports the complete cycle of Java program development. Using the rapid
application development environment provided by VisualAge for Java, you
can shorten the development cycle of your applications.
The VisualAge for Java product family includes workstation and OS/390
components. Some customers will prefer to do their Java application
development for IMS using exclusively mainframe tools. Others will opt for a
workstation application development environment. In this project we used
both mainframe and workstation environments, which we describe in Chapter
2, “Environment customization” on page 23.
VisualAge for Java is available in three versions:
Entry Edition
Professional Edition
Enterprise Edition
Chapter 1. Introduction 19

If you choose VisualAge for Java as your workstation development
environment for IMS, use the Enterprise Edition on your workstation. You can
also use another Java integrated development environment (IDE) workbench
or not use any workbench at all. In any case, you have to order VisualAge for
Java, Enterprise Edition for OS/390, to support compilation and binding of
Java programs for use in the IMS environment.
1.5.8 VisualAge for Java tools
Several tools in VisualAge for Java, Enterprise Edition, facilitate the
application development process for OS/390 and IMS:
1.5.8.1 Remote debugger
You can remotely debug your fully compiled and bound Java programs
running natively in the OS/390 UNIX environment or under IMS. The remote
debugger has an intuitive GUI that you can use to debug your code at the
source level. You can set breakpoints by line number, on method entry, or on
a storage chain. You can display and monitor variables, registers, memory,
and call stacks or display your variables. You can single-step through your
code or step into or around methods. You can set frequency counts for line
breakpoints to stop program execution at specific iterations.
1.5.8.2 Performance analyzer
You can use the ET/390 Performance Analyzer on your workstation to
graphically display and analyze a trace of the execution of fully compiled and
bound programs running in your OS/390 UNIX environment. This tool does
not support execution under IMS.
1.5.8.3 jport utility
The jport utility is used to identify code that cannot be optimized with the HPJ
compiler, which targets natively compiled code for the OS/390 UNIX and IMS
environments; for example, the java.applet package and AWT are not
supported. The jport utility reads Java bytecode files and generates a report
that lists all unsupported packages, classes, methods, and fields for the
OS/390 UNIX and IMS environments. The jport utility can be invoked
automatically when you use VisualAge for Java to export and bind your
program. Alternatively you can invoke the jport utility directly from the
command prompt on your workstation to verify Java bytecode files that are on
your local workstation, or from the OS/390 UNIX shell to verify Java code that
is on your OS/390 Hierarchical File System (HFS).
20 IMS Version 7 and Java Application Programming

1.5.9 Java application structures
In the Java environment you deal with several types of application structures.
1.5.9.1 Application
Java applications are real Java programs. They can process local files,
contact other systems on the network, and do many other things Java applets
cannot do. Java applications can create their own security manager, which
can persist for the duration of the application and set the security rules for the
application. An application would typically be preinstalled on the system on
which it is to run in the same way as applications written in other languages.
Java applications can be made available through a network and in fact are
suited to this type of configuration. You can use NFS, WebNFS, DFS, or
another network-based file system, rather than distributing the application to
each individual system (PC or workstation) on which it will run. Java
applications have a main() construct in their source code; this defines the
top-level class. Applets and servlets, by contrast, do not have a main()
construct.
1.5.9.2 Applets
Java applets are mini-programs and must be run by either the Java JDK
appletviewer or by a Java-enabled Web browser.The applet class, a special
type of Java application, can only exist within another application that can
create or initiate it. The JDK appletviewer or a Java-enabled Web browser are
two such applications. Over time it is reasonable to expect that other
applications, such as word processors, will be able to run Java applets.
Typically, Java applets reside on a Web server. When a Web server returns a
page that contains a pointer to a Java applet through an tag, the
Java-enabled Web browser requests the applet from the server. Once
received, either the browser starts the applet internally, or the external JVM
executes it. Java applets do not require Java execution environment to be
available on the server.
During execution, the applet may require other classes that are not available.
These classes will be brought over the network by the Java class loader. The
classes are compiled Java bytecode, not source code.
Applets have no access to operating system or hardware; this is a function of
inheriting from the Java applet class and is restricted by the JVM. Applets can
have no access, restricted access, or unrestricted access to the Internet or
intranet. Software, hardware, and network access is controlled by built-in
Java security.
Chapter 1. Introduction 21

1.5.9.3 Servlets
A servlet is to a Web server what an applet is to a Web browser. It is a way of
extending the function of the Web server beyond the standard facilities
offered by that server. Unlike other technologies that do this, such as
Common Gateway Interface (CGI), Internet Connection Application
Programming Interface (ICAPI), Go Webserver Application Programming
Interface (GWAPI), servlets use Java and adhere to Sun's servlet model.
WebSphere Application Server and other plug-ins make servlets portable not
only between platforms but also between Web servers from different
manufacturers.
As with an applet, a servlet has no main() construct. It is initiated, serviced,
and destroyed by the Web server.
1.5.9.4 Beans
JavaBeans are the component technology for Java. They are both a
mechanism for packaging Java components and an infrastructure for creating
and instantiating the components. JavaBeans can “describe” themselves to a
development environment; that is, they can be imported in bytecode class file
format and then disclose the public methods and properties they have and
that can be set, retrieved, and called at execution time.
It is possible to download and use Beans from a network, and to devise test
cases for each Bean to make sure it meets your requirements before you use
it in an application.
Although Beans are often graphical, representing visual components, they do
not have to be. An IDE such as VisualAge for Java can import both visual and
nonvisual Beans, and these Beans can be "wired" together when building
applications, applets, servlets, or other JavaBeans.
1.5.10 Access to hardware
The set of APIs delivered with the standard JDK is very rich. Unfortunately, it
cannot cover every situation. Most importantly, you cannot access specific
hardware from Java, because that would hamper portability. However, if
developers want to access specific hardware, they obviously do not care
much about portability. For this purpose, Java offers the Java Native Interface
(JNI), a set of APIs that can call native routines (written, for example, in C)
and allow native programs to call Java methods.
With JNI, a Java program running on OS/390 can call a native program
written, for example, in C, and access S/390 resources. Data can be passed
back and forth between the Java code and the C code.
22 IMS Version 7 and Java Application Programming

Chapter 2. Environment customization
In this chapter, we describe the tasks necessary to set up the environment for
developing and running Java programs in IMS. Java programs can be
developed on a workstation, using a GUI environment such as Visual Age for
Java Enterprise Edition, or in the OS/390 UNIX System Services shell. The
programs are then compiled with the OS/390 HPJ compiler to create a
high-performance runtime module as either an HFS executable or a Data Link
Library (DLL) member in a PDSE.
IMS Version 7 supports Java in two ways:
2.1 Required software levels
It provides the facility that allows IMS transactions to be written in Java
language as a substitute for COBOL, PL/1, or C.
External Java applications can communicate with an IMS transaction by
means of a connector called IMS Connect.
Major software prerequisites and minimum release levels for enabling IMS
Java are shown below. Detailed installation and setup information follows.
IMS V7 Transaction Manager
OS/390 R2.6 (or higher)
OS/390 LE V1 R7
Visual Age for Java Enterprise Edition for OS/390
JDK 1.1.8
DB2 V5 with APAR PQ19814 (if DB2 access will be required)
2.1.1 NFS and FTP server tasks
An NFS server and an FTP server are required on OS/390, and an NFS client
and FTP client are required on the workstation for workstation-to-OS/390
remote file access and file transfer operations.
The FTP Server on OS/390 is part of the base TCP/IP facilities. These
facilities are part of the OS/390 base support from OS/390 V2 R4 and later
(in OS/390 V2 R7, the TCP/IP facilities will be known as eNetwork
Communications Server facilities).
2.1.2 Java Development ToolKit (JDK) 1.1.8
Installation and setup details for the JDK are described next.
© Copyright IBM Corp. 2001 23

2.1.2.1 JDK 1.1.8 installation and setup
At the time of writing, the latest generally available version of the
JavaDevelopment Toolkit for OS/390 is JDK 1.1.8 and is downloadable from
the following URL:
http://www.ibm.com/s390/java
In addition, this URL outlines the latest prerequisites and instructions, and
you will be able to download the latest JDK available for OS/390. You can
also order the latest version on tape, which includes a program directory
containing the prerequisites and the instructions.
For the latest information regarding prerequisites for Java on OS/390, you
can refer to the URL:
http://www.ibm.com/s390/java/javainst.html#prer
For information regarding installation of Java for OS/390, refer to the URL:
http://www.ibm.com/s390/java/javainst.htm
2.1.2.2 Directory structure
You should decide from the beginning about the directory structure in which
the JDK and other Java-related products will be installed. A possible structure
is to create the /usr/lpp/java/ directory. Then, in this directory, unpack the
downloaded JDK install file.as explained in, ‘Installation method: Tar and
Tarball files’ The unpacking will create a subdirectory named J1.1 in the same
/usr/lpp/java/ directory. You may also install JDBC and other Java-related
packages in the same directory structure.
2.1.2.3 Installation method: Tar and Tarball files
There are two ways of installing the JDK:
1. Download a Tar file and manually install it.
2. Download a Tarball file and install it with SMP/E.
If you choose the first solution, you will have to download a Tar file (a file
made with the OS/390 UNIX System Services tar utility) and install it. You
can either enter manual UNIX commands to “untar” the file, or run a utility
called ajvinst.exec.
This is a REXX installation script that is downloadable from the same place
as the Tar or Tarball files.The second solution uses SMP/E. The Tarball file
contains the SMP/E jobs and the program directory. Run the ajvinst.exec
installation script to uncompress and install the Tarball.
24 IMS Version 7 and Java Application Programming

2.1.2.4 Downloading the JDK
Go to this URL for downloading the JDK onto your workstation:
http://www.ibm.com/s390/java/register.html
Then, after registration, follow the directions to transfer the JDK compressed
file to your workstation. After having stored the JDK compressed file on your
workstation, transfer it to your OS/390 server using FTP. Initiate the FTP
session from the workstation, using the FTP server running in the OS/390
machine.
2.1.2.5 Verifying the installation
Your path should contain the binary directory where java is located. Type:
export PATH=/usr/lpp/java/J1.1/bin:$PATH
Now, verify that Java is correctly installed by typing:
java -fullversion
Java should reply with the correct version and the build date of the JDK.
2.1.3 Visual Age for Java, Enterprise Edition for OS/390
VisualAge for Java, Enterprise Edition for OS/390 Version 2, product number
5655-JAV, when ordered with OS/390 V2R7.0, is provided with an
IBM-supplied IFAPRD00 member that contains the required PRODUCT
statements to enable the VAJAVA/390-DEBUG feature. This feature provides
the required Debug/Performance Analyzer functions.
The NFS client on the workstation is not part of the base functions of
Windows NT and you will need to install an NFS client such as Hummingbird
NFS Maestro. The NFS Server on OS/390 is part of the base elements of
OS/390 for OS/390 V2R4 and later releases. The NFS Server was known as
DFSMS/MVS NFS until OS/390 V2R6, at which time it became exclusive to
OS/390, had function added to it, and is now known as NFS.
2.1.3.1 Installation of VisualAge for Java, Enterprise Edition OS/390
The installation of the HPCJ Run Time Library and the HPCJ Compiler,
Program Number 5655-JAV, is provided through two FMIDs:
FMID H0A5201 — VisualAge for Java Compiler, priced
FMID H0A5202 — VisualAge for Java Run Time Library, no charge
The installation of these two FMIDs is detailed in the Program Directory for
VisualAge for Java, Enterprise Edition for OS/390, Program Number
5655-JAV, Document Number GI10-4949 (product documentation).
Chapter 2. Environment customization 25

2.1.4 The HPJ compiler Installation on OS/390
The installation of the HPJ Run Time and the HPJ Compiler are described in
detail in the Program Directory for VisualAge for Java, Enterprise Edition for
OS/390, Program Number 5655-JAV, Document Number GI10-4949 (product
documentation). As part of the SMP/E installation for both FMIDs, sample
jobs are provided that assist in the installation of VisualAge for Java. These
jobs and the changes that must be made to them for the specific installation
configuration,.as well as the steps that must be followed to perform the jobs,
are described in the Program Directory product documentation.
VisualAge for Java, Enterprise Edition for OS/390 Version 3, product number
5655-JAV, when ordered with OS/390 V2R7.0, is provided with an
IBM-supplied IFAPRD00 member that contains the required PRODUCT
statements to enable the VAJAVA/390-DEBUG feature. This feature provides
the required Debug/Performance Analyzer functions.
2.1.5 OS/390 UNIX System Services environment
This section covers the OS/390 UNIX System Services environment.
2.1.5.1 Setup of directories on UNIX System Services
The HFS directories are set up as a result of the HPOISMKD and the
HPJISMKD jobs for the VisualAge for Java, Enterprise Edition for OS/390
Run Time Library and the VisualAge for Java, Enterprise Edition for OS/390
HPCJ Compiler respectively.
When the installation of the Run Time Library and the HPCJ Compiler is
complete, it is necessary to set the environment variables for IBMHPJ_HOME,
CLASSPATH, LIBPATH, and STEPLIB to the appropriate values.STEPLIB should
include HPJ.SHPOMOD, HPJ.SHPJMOD, and CEE.SCEERUN.
When both the VisualAge for Java Run Time Library and the VisualAge for
Java Compiler have been installed, the contents of the file with default name
/usr/lpp/hpj/bin/profile.hpj as shown in Figure 6 should be appended to
/etc/profile for use by everyone, or copied into $HOME.profile for individual
use and updated to reflect the values used in your environment.
26 IMS Version 7 and Java Application Programming

etc/profile for general use or to the
/u//.profile for individual user use.
export IBMHPJ_HOME=/usr/lpp/hpj 1
export IBMHPJ_RTL="CEE.SCEELKED:CEE.SCEELKEX:CEE.SCEEOBJ:CEE.SCEECPP" 2
export CLASSPATH=$IBMHPJ_HOME/lib:$CLASSPATH 3
export PATH=$IBMHPJ_HOME/bin:$PATH 4
export LIBPATH=$IBMHPJ_HOME/lib:$LIBPATH 5
export STEPLIB=$STEPLIB:HPJ.SHPJMOD:HPJ.SHPOMOD:CEE.SCEERUN 6
Figure 6. Example of HPJ variables in /etc/.profile
The system programmer should append the updated profile.hpj file to
/etc/profile for general use or to the /u/”username”/.profile for individual
use (see Figure 7 and Figure 8):
1. Set the home variable for the HPJ root.
2. Required LE support for HPJ compiler; CEE was used as the high level
qualifier.
3. Append the CLASSPATH with the HPJ classes.
4. Append the PATH with the HPJ executables.
5. Append the LIBPATH with the executables.
6. HPJ was used as the high level qualifier.
#================================================
#JDK
#================================================
export JAVA_HOME=/usr/lpp/java18i/J1.1
export PATH=/usr/lpp/java18i/J1.1/bin:$PATH
export CLASSPATH=/usr/lpp/java18i/J1.1/lib/classes.zip:$CLASSPATH
export LD_LIBRARY_PATH=/usr/lpp/java18i/J1.1/lib/classes.zip:$LD_LIBRARY_PATH
Figure 7. JDK.profile file
export IBMIMSJ_HOME=/usr/lpp/ims/imsjava71/classes.zip
export CLASSPATH=$CLASSPATH:$IBMIMSJ_HOME
echo ‘*------------------------------------------------------------------------*’
echo ‘profile.imsjava executed ------------------------------------------------*’
echo ‘*------------------------------------------------------------------------*’
Figure 8. IMSJAVA.profile file
Chapter 2. Environment customization 27

2.1.5.2 TSO/E storage considerations
If you experience memory shortage when you execute the hpj command, you
might have to log on to TSO with a larger address space (SIZE field on the
TSO/E logon panel). The maximum value for an address space size is set up
by MAXASSIZE parameter in SYS1.PARMLIB(BPXPRM00). We set ours to
MAXASSIZE(2147483647), which is the maximum.
2.2 Workstation environment
This section describes the requirements to set up your workstation
environment.
2.2.1 Prerequisites
A 300 MZ or faster processor with a minimum of 256 MB RAM is
recommended. Also, available free disk space of 1 GB is suggested.
2.2.2 Required software
2.2.3 NFS client
We recommend Microsoft Windows NT Workstation V4.0 with SP4, SP5,
or SP6+.
TCP/IP Networking is required.
JDK 1.1.8
Visual Age for Java 3.0.2
An NFS server and an FTP server are required on OS/390, and an NFS client
and FTP client are required on the workstation for workstation-to-OS/390
remote file access and file transfer operations.
2.2.3.1 NFS connections
An NFS connection between the NFS Client on your workstation and the NFS
Server on OS/390 is required. The connection is used to import and export
java source and bytecode to and from Visual Age for Java on the workstation.
The OS/390 NFS Server must be installed on the OS/390 system. Refer to
2.1.1, “NFS and FTP server tasks” on page 23 for more information.
On the workstation, we are using Network Access Suite 3.0 for NT as our
NFS Client. The setup box for the authentication server connection is shown
in Figure 9.
28 IMS Version 7 and Java Application Programming

Figure 9. NFS Network Access Suite connection customization
Once the NFS client is installed on the development workstation, the network
connections to the HFS on the OS/390 server have to be established. Figure
10 shows how to make these connections from an MS-DOS prompt.
The net use command comes as part of the Windows NT workstation
software. It allows you to have an NFS connection to windows resources, but
in order to connect to OS/390 resources, you will need to have an NFS client
such as Network Access Suite 3.0 installed. The net use command usage is
as follows:
Chapter 2. Environment customization 29

For a binary connection to OS/390:
NET USE devicename: \\domainname\/hfs/targetdirectory,binary password
/USER:username
For a text connection to OS/390:
NET USE devicename: \\domainname\/hfs/targetdirectory,TEXT password
/USER:username
Once the net use command is submitted, you should receive a message
“The command completed successfully.” To check the connections on the NT
workstation, simply enter the net use command as seen in Figure 10.
Figure 10. Establishing NFS connections using net use in MS-DOS
2.2.3.2 FTP links
The FTP client is part of the base functions of Windows NT and requires no
special configuration for VisualAge for Java, Enterprise Edition for OS/390 to
be able to use it.
30 IMS Version 7 and Java Application Programming

Chapter 3. Building an IMS Java application
The IMS Java class libraries allow you to write IMS applications in Java.
Below is a description of how to write an application using the IMS Java class
libraries with access to necessary IMS services.
3.1 Overview of IMS application processing
The IMS Java classes allow you to write the following types of applications:
Message Processing Programs (MPPs)
IMS Fast Path Programs (IFPs)
Batch Message Processing Programs (BMPs)
Ordinarily, in IMS, before deciding upon which types of programs to use, you
need to determine the working environment, that is, DB/DC, batch, or DBCTL.
However, IMS Java currently only supports the DB/DC environment.
In IMS, your program type would also depend upon the type of database that
you are connecting to, either:
Full-Function
DB2
Fast Path
Other database types
However, all these database types (and others) can be processed by all the
program types that IMS Java supports, as listed above, in the DB/DC working
environment.
3.1.1 Message processing programs (MPPs)
MPPs are online programs that process and reply to messages quickly. MPPs
are executed through transaction codes submitted by users at terminals and
from other application programs, where each transaction code represents a
transaction that the MPP processes. A single program can also be started
from multiple transaction codes.
These programs are very flexible in how they process transactions and where
they send the output. An MPP is started when there is a message in the
queue for the MPP; and MPPs are designed to continue to run until there are
no more messages. MPPs are:
Small
Able to produce output that is needed immediately
© Copyright IBM Corp. 2001 31

3.1.2 IMS Fast Path programs (IFPs)
IFPs are online programs similar to MPPs in that they are used for quick
processing. However, IFPs provide faster response and allow higher volumes
of processing because they:
Take advantage of the Expedited Message Handler (EMH)
Process messages that consist of only one segment
Process messages faster because they do not rely on queuing for
processing
Run in transaction response mode, where the terminal must wait for the
IFP to respond before submitting any more requests
Process only wait-for-input transactions where the program remains in
virtual storage, even if there are no other messages available for
processing
Are the only program running in a region
Do not end when there are no more messages, but must be explicitly
stopped by an operator
3.1.3 Batch message processing programs (BMPs)
BMPs are flexible programs that perform batch-type processing online and
access the IMS message queues for their input and output. BMPs are started
by submitting a batch job, for example by a user by way of TSO or with a job
scheduler. Two types of BMPs are:
Batch-oriented
Transaction-oriented
IBM recommends that you use BMPs to write batch programs instead of DL/I
batch processing because BMPs better lend themselves to data sharing.
3.2 Message processing applications
After determining the appropriate program to use, you must give your
program specific instructions from the terminal in order to use it. You can
access programs from the terminal by providing one of these types of input:
Commands These start with slash (/), for example: /START.
Transaction message To be routed to an application program for
processing. The program destination is defined by
the 1 to 8-byte transaction code included as the
first part if the input.
32 IMS Version 7 and Java Application Programming

Message switch To be routed to another terminal.The terminal
destination is defined by the 1 to 8-byte terminal
name included as the first part if the input.
Related reading
See the IMS Operator’s Reference, SC26-9436-00 for more information
on IMS commands.
3.2.1 Message queuing
Once the input has been issued, the message is either queued or sent
directly to command process or modules.
Specifically, all Full-Function database input and output messages are
queued in message queues, waiting to be enqueued to their destinations —
their points of completion. However, before getting to the points of
completion, IMS message queues are held in buffers in main storage until
they are either directed to their destination or until there is a backlog of
messages arriving in the queue. If there are more messages entering the
queue than exiting, IMS writes messages to the message queue data sets
until they are directed to their final destination.
However, for all Fast Path transactions, messages are handled within the
Transaction Manager by the Expedited Message Handler (EMH).
Related reading
See the IMS Application Programming: Design Guide, SC26-9423-00 for
more information on IMS program types.
See the V7 IMS Primer, SG24-5352-00 for general information on IMS
message queues.
3.2.2 Reading and writing messages to the message queue in Java
A basic IMS Java application involves input of and the receipt of multiple
messages from the message queue much like applications in other
languages. IMS Java applications are invoked by transactions, where a
person at a terminal can communicate with the application program and IMS.
The actual applications are built with the application package classes, using
the IMS Java classes and methods.
Chapter 3. Building an IMS Java application 33

3.3 Building an IMS Java application by example
In this and the next chapter we are introducing a sample auto dealership
program for illustration purposes.
3.3.1 Introduction to the example environment
The sample database contains 5 segment types as shown in Figure 11. The
root segment is the Dealer segment. Its child segment is the Model segment.
Under the Model segment are its children; the segments Order, Stock, and
Sales.
Figure 11. Database view of all segments
The Dealer segment identifies a dealer selling cars. The segment contains a
unique dealer number, dealer name and address, and annual sales
information. Dealers carry car types, each of which has a corresponding
Model segment. A Model segment contains a unique type code, descriptive
information about the car and its price.
There is an Order segment for each car ordered for the dealership itself. The
segment is sequenced by an order number that contains information about
the options, pricing, order date, and the customer who ordered the car. When
a car is delivered to fill a particular order, its serial number and delivery date
are added to the segment. The segment is deleted when the customer (or
dealer) accepts the car.
34 IMS Version 7 and Java Application Programming
Dealer
Model
Order Sales Stock

A Stock segment is created for each car that is available for sale in the
dealer’s inventory. The segment is sequenced by a serial number that is
unique to a given model. It contains descriptive information about the car and
the date it was delivered to the dealer. The segment remains in the database
until the car is sold from delivery.
Finally, when the car is sold, a Sales segment is created. This segment is
sequenced by sale date and contains information about the car sold and the
purchaser.
3.3.2 Building an IMS Java message processing application
A model of an IMS Java message processing application consists of these
steps:
Subclassing IMSApplication and implementing your entire application in
the doBegin method of your subclass. The doBegin method is an abstract
method in the base class, IMSApplication. The main method of your
subclass must call the begin method of the base class, IMSApplication.
The begin method of the base class then performs initialization and calls
the abstract doBegin method that was implemented in your subclass.
Receiving and sending IMSFieldMessages
Performing a commit before processing the next message or terminating
the application by calling IMSTransaction.getTransaction().commit()-.
3.3.2.1 Subclass IMSFieldMessage to define any input messages
Subclass IMSFieldMessage to define your application’s input messages.
1. Subclass IMSFieldMessage to make the fields in a message available to
our Java program.
2. Identify the field name, data type, position, and length of the individual
fields within the byte array. This allows your application to use the
accessor functions within IMSFieldMessage to automatically convert the
data from its format in the message to a Java type that your application
can process. In addition to the message-specific fields you define,
IMSFieldMessage provides accessor functions that allow you to determine
the transaction code and the length of the message.
The example input code in Figure 12 accepts a two-byte car model type code
to query a car dealership database for available car models.
Chapter 3. Building an IMS Java application 35

package dealership.application;
import com.ibm.ims.db.*;
import com.ibm.ims.base.*;
import com.ibm.ims.application.*;
public class InputMessage extends IMSFieldMessage { a
final static DLITypeInfo[]fieldInfo={
new DLITypeInfo("ModelTypeCode", DLITypeInfo.CHAR, 1, 2)b
};
public InputMessage() {
super(fieldInfo, 2, false);
}
}
Figure 12. Example to define Input messages
3.3.2.2 Subclass IMSFieldMessage to define any output messages
Subclass IMSFieldMessage to define your application’s input messages.
1. Subclass IMSFieldMessage.
2. Identify the data type.
3. Identify the field name.
4. Identify the position.
5. Identify the length in the byte array.
The example output code in Figure 13 will output a match for the car model
input type code.
package dealership.application;
import com.ibm.ims.db.*;
import com.ibm.ims.base.*;
import com.ibm.ims.application.*;
public class ModelOutput extends IMSFieldMessage { a
final static DLITypeInfo[] fieldInfo={
new DLITypeInfo("Type", DLITypeInfo.CHAR, 1,2), b
new DLITypeInfo("Make", DLITypeInfo.CHAR, 3, 10), c
new DLITypeInfo("Model", DLITypeInfo.CHAR, 13,10), d
new DLITypeInfo("Year", DLITypeInfo.DOUBLE,23,4), e
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 13. Example to define Output messages
36 IMS Version 7 and Java Application Programming

3.3.2.3 Subclass IMSApplication and implement main and doBegin()
The example code in Figure 14 does the following things:
1. Subclasses IMSApplication.
2. Instantiates the subclass in the main method.
3. Calls IMSApplication.begin.
4. Implements the application within the overridden version of doBegin().
5. Queries the database for a specific model that matches the input model
type code. This method is not implemented yet and is explained more fully
in Chapter 5, “Accessing an IMS database” on page 49.
6. Returns detailed information as output about that specific model if it is
available at the dealership.
7. Returns an error message if the model is not available at the dealership.
package dealership.application;
import com.ibm.ims.application.*;
public class IMSAuto extends IMSApplication { a
IMSMessageQueue messageQueue = null;
InputMessage inputMessage = null;
ModelOutput modelOutput = null;
public IMSAuto() {
super();
}
public static void main(String args[]){
IMSAuto imsauto = new IMSAuto(); b
imsauto.begin(); c
}
public void doBegin() throws IMSException { d
messageQueue = new IMSMessageQueue();
inputMessage = new InputMessage();
modelOutput = new ModelOutput();
while(messageQueue.getUniqueMessage(inputMessage)) {
if (!inputMessage.getString("ModelTypeCode").trim().equals("")) {
if (getModelDetails(inputMessage, modelOutput)) e
messageQueue.insertMessage(modelOutput); f
}
else {
reply("Invalid Input"); g
}
IMSTransaction.getTransaction().commit();
}
}
public void reply(String errmsg) throws IMSException{
ErrorMessage errorMessage = new ErrorMessage();
errorMessage.setString("MessageText",errmsg);
messageQueue.insertMessage(errorMessage);
}.
Figure 14. Example to Implement Main and doBegin()
Chapter 3. Building an IMS Java application 37

Notice that IMSMessageQueue.getUniqueMessage returns the boolean
true if a message was read from the queue and false if one was not. Also,
IMSTransaction.getTransaction().commit must be called prior to receiving
subsequent messages from the queue.
38 IMS Version 7 and Java Application Programming

Chapter 4. Conversational transactions
A conversational program is an MPP that processes transactions made up of
several steps. It does not process the entire transaction at the same time. A
conversational program divides processing into a connected series of
terminal-to-program-to-terminal interactions. You use conversational
processing when one transaction contains several parts.
A nonconversational program receives a message from a terminal, processes
the request, and sends a message back to the terminal. A conversational
program receives a message from a terminal, and replies to the terminal, but
saves the data from the transaction in a scratch pad area (SPA). Then, when
the person at the terminal enters more data, the program has the data it
saved from the last message in the SPA, so it can continue processing the
request without the person at the terminal having to enter the data again. The
Application Package classes enable applications to be built using IMS Java.
Related reading:
For more information on conversational and nonconversational transaction
processing, see the IMS V7 Administration Guide: Transaction Manager,
SC26-9421-00.
4.1 Defining an SPA message
Here are the steps to define a SPA message in a conversational program:
1. Define the SPA message (including the boolean isSPA parameter). By
default, all messages going to (input) and from (output) an IMS Java
application are transmitted as EBCDIC character data. To use a different
type of encoding, you must call the IMSFieldMessage inherited member
setDefaultEncoding and provide the new encoding. The encoding can be
any Java supported encoding. In Figure 15, the default encoding is
specified as UTF-8.
© Copyright IBM Corp. 2001 39

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 15. SPA Message code (1)
2. Read the SPA message before reading the application messages
(Figure 16).
try {
// Get the SPA data
msgReceived = msgQ.getUniqueMessage(spaMessage);
}
catch (IMSException e)
{
if (e.getStatusCode() !=
JavaToDLI.MESSAGE_QUEUED_PRIOR_TO_LAST_START)
throw e;
}
if (!msgReceived)
outputMessage.setString(“Message”,”UNABLE TO READ SPA”);
else if (!msgQ.getNextMessage(inputMessage))
// No input message received
outputMessage.setString(“Message”,”NO INPUT MESSAGE”);
else if ((spaMessage.getShort(“SessionNumber”)==0)
&& (!inputMessage.getString(“ProcessCode”).trim().equals(“END”))
&& (inputMessage.getString(“LastName”).trim().equals(“ “)))
// New Conversation. User has to specify last name.
outputMessage.setString(“Message”,”LAST NAME WAS NOT SPECIFIED”);
else
{
Figure 16. SPA Message code (2)
3. Write the SPA message before sending any output messages (Figure 17).
40 IMS Version 7 and Java Application Programming

Set spa data fields
spaMessage.setString("ProcessCode",
inputMessage.getString("ProcessCode"));
spaMessage.setString("LastName",
inputMessage.getString("LastName"));
spaMessage.setString("FirstName",
inputMessage.getString("FirstName"));
spaMessage.setString("Extension",
inputMessage.getString("Extension"));
spaMessage.setString("ZipCode",
inputMessage.getString("ZipCode"));
spaMessage.incrementSessionNumber();
msgQ.insertMessage(spaMessage);
Figure 17. SPA Message code (3)
4. Terminate the conversation using the version of insertMessage containing
a boolean isLast argument set to true:
msgQ.insertMessage(spaMessage, true);
4.2 Conversational transaction sequence of events
When the message is a conversational transaction, the following sequence of
events occurs:
1. IMS removes the transaction code and places it at the beginning of a
message segment. The message segment is equal in length to the SPA
that was defined for this transaction during system definition. This is the
first segment of the input message that is made available to the program.
The second through the nth segments from the terminal, minus the
transaction code, become the remainder of the message that is presented
to the application program.
2. When the conversational program has prepared its reply, it inserts the SPA
to IMS. The program then inserts the actual text of the reply as segments
of an output message.
3. IMS saves the SPA and routes the message to the input LTERM (logical
terminal).
4. If the SPA insert specified that another program is to continue the same
conversation, the total reply (including the SPA) is retained on the
message queue as input to the next program. This program then receives
the message in a similar form.
Chapter 4. Conversational transactions 41

5. A conversational program must be scheduled for each input exchange.
The other processing continues while the operator at the input terminal
examines the reply and prepares new input messages.
6. To terminate a conversation, the program places blanks in the transaction
code field of the SPA, and inserts the SPA to IMS. In IMS Java this
happens when you call IMSMessageQueue.insertMessage with the
boolean parameter isLast set to true.
7. The conversation can also be terminated if the transaction code in the
SPA is replaced by any non conversational program’s transaction code,
and the SPA is inserted to IMS. After the next terminal input, IMS routes
that message to the other program’s queue in the normal way.
4.2.1 Defining subsequent input messages
In order to utilize multi-segment messages, you must map subsequent input
messages. Figure 18 is an example of a class to map a second input
message. The default encoding is UTF-8.
public class InputMessage2 extends IMSFieldMessage {
final static DLITypeInfo[] segmentInfo = {
new DLITypeInfo(“Field1”, DLITypeInfo.CHAR, 1, 10),
new DLITypeInfo(“Field2”, DLITypeInfo.INT, 11, 4)};
public InputMessage2() {
super(““, segmentInfo, 14);
setDefaultEncoding (UTF-8”);
}
}
Figure 18. Subsequent Input Message code
4.3 Using DLIConnection to access a database
While it is possible to use this lower level package to access IMS data, we
recommend that you use the JDBC package. This package is included for
experienced IMS application developers who need more access than the
higher level package provides. This style of the database package contains
the following objects and classes:
4.3.1 DLIConnection
A DLIConnection object represents a connection with a DL/I database. It
provides the interface to read, update, insert, and delete segments in a DL/I
database.
42 IMS Version 7 and Java Application Programming

4.3.2 DLISegment
DLISegment is the abstract base class for objects representing segments in a
DL/I database. It allows a subclass to register the types of data stored in a
segment by providing an array of DLITypeInfo objects. Setter and getter
functions use the type information to automatically locate and convert data in
the byte array to the requested format. These setter and getter functions can
locate data based on both its offset in the DLITypeInfo array (fastest) or using
the name of the field included in the type information.
4.3.3 DLITypeInfo
DLITypeInfo, contained in the base package, defines the type, offset, and
length of a field in the byte array of a DLISegment. It supports all DB2 for
OS/390 data types, including packed decimal.
4.3.4 SSA
SSA represents a Segment Search Argument. It provides functions to add
command codes and qualification statements.
4.3.5 SSAList
SSAList represents a collection of SSA objects and converts the list to the
byte array necessary to invoke the JavaToDLI functions. The combination of
SSAList, SSA, and SSAQualification statement allows an application to
specify a Segment Search Argument list that fully supports all of its features.
4.3.6 SSAQualificationStatement
An SSAQualificationStatement represents logical qualification statements to
a Segment Search Argument. Qualification statements support both key
search fields and search fields.
4.3.7 DLIRecord
DLIRecord represents the set of segment occurrences from a root segment
down the hierarchy to the leaf segment. The DLIConnection methods
getUniqueRecord and getNextRecord update a DLIRecord object using a
path call (“D” command code). DLIRecord primarily exists to support JDBC
queries that return results from multiple segments in a segment path.
4.3.8 DLISegmentInfo
DLISegmentInfo is a “wrapper” class that links a DLISegment object to its
parent in the DL/I database hierarchy.
Chapter 4. Conversational transactions 43

4.3.9 DLIDatabaseView
DLIDatabaseView represents an application’s view of the segments in a DL/I
database. It is built as an array of DLISegmentInfo objects which bind a
DLISegment object to its parent DLISegment object and therefore defines the
segment hierarchy. DLIDatabaseView provides named lookup of the
DLISegment objects, and this feature is used by the DL/I JDBC
implementation to locate a DLISegment object from the name of a segment
used in a query.
4.4 Application programming using DLIConnection
To use DLIConnection to read, update, insert, and delete segment instances,
your application should:
1. Provide a subclass of DLISegment for each segment accessed in the
database that identifies the types of data stored in the segment
2. Provide a subclass of DLIDatabaseView that defines the segment
hierarchy accessed by the application
3. Create a DLIConnection object to access the database
4. Create an SSAList Object.
5. Invoke the database access functions of DLIConnection to read, write, or
delete segments from the database
4.5 Subclassing DLISegment
The method for subclassing DLISegment is the same as described in 5.1.3.1,
“DLISegment example” on page 52.
4.5.1 Coding messages with repeating structures
Messages with repeating structures can be defined using a subclass of
DLITypeInfo called DLITypeInfoList. DLITypeInfoList allows you to define an
array of repeating structures in one object instead of multiple, individual
DLITypeInfo objects. DLITypeInfoList is an object that stores an array of
DLITypeInfo objects along with a count of its occurrences, thus allowing an
input message to contain nested repeating structures.
The code in Figure 19 is an example of an output message containing a set of
Make, Mode and Color fields, along with a count field to identify how many
occurrences were stored.
44 IMS Version 7 and Java Application Programming

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[] modelTypeInfo = {
new DLITypeInfo(“ModelCount”, DLITypeInfo.INTEGER, 1, 4),
new DLITypeInfoList(“Models”, modelTypeInfo 5, 60, 100),};
public ModelOutput() { super(modelOutputTypeInfo, 6004, false);
}}
Figure 19. Sample DLITypeInfo statement
Note
The creation of the DLITypeInfoList object has no provision for specifying
its type. DLITypeInfoList hard codes the type of the fiels to
DLITypeInfo.TYPELIST. This design is not constrained to any specific level
of nesting. Within the declaration of model TypeInfo above, any of the array
members could be instances of DLITypeInfoList
To access the nested structures defined in a DLITypeInfoList, use a dotted
notation for specifying the fields and the index of the field within a repeating
structure. This dotted notation can use either the field names or field indexes.
For example, the Color field in the fourth Models definition in ModelOutput
would be accessed as Models.4.Color within the Model Output message. The
code in Figure 20 sets the fourth Color in the ModelOutput message to Red.
ModelOutput output= new ModelOutput();
output.setString(“Models.4.Color”, “Red”);
Figure 20. The use of dotted notation
The code in Figure 21 uses field indexes instead of field names to make the
same change to the ModelOutput message.
ModelOutput output= new ModelOutput();
output.setString(“2.4.3”, “Red”);
Figure 21. The use of field indexes
Chapter 4. Conversational transactions 45

4.5.2 Accessing messages with repeating structures
A dotted notation is used for specifying the fields and the index of the field
within a repeating structure. For example, the Color field in the fourth Models
definition in ModelOutput would be accessed as Models.4.Color within the
ModelOutput message. The code in Figure 22 sets the fourth Color in the
ModelOutput message to Red.
ModelOutput output= new ModelOutput();
output.setString(“Models.4.Color”, “Red”);.
Figure 22. Another example of dotted notation
Note
JDBC 1.0 does not support the concept of nested or repeating structures,
so IMS Java does not support access to nested structure fields from a
JDBC query.
4.6 Subclassing DLIDatabaseView
The method for subclassing DLIDatabaseView is the same as described in
5.1.2.1, “DLIDatabaseView example” on page 51.
4.6.1 Creating a DLIConnection Object
A DLIConnection object must be created in one of two ways. This can be
done by providing a DLIDatabaseView object, or by providing the fully
qualified name of the DLIDatabaseView. When providing the fully qualified
name of the DLIDatabaseView, be sure to use the -include option when you
compile your application. When coding directly to DLIConnection, it is faster
to create and pass the DLIDatabaseView object as it saves the overhead of
finding the class by its name. Figure 23 is an example of creating a
DLIConnection object.
DealerDatabaseView dealerView = new DealerDatabaseView();
DLIConnection connection = DLIConnection.createInstance(dealerView);
Figure 23. Sample DLIConnection statement
46 IMS Version 7 and Java Application Programming

4.6.2 Using SSAs to access DL/I information
SSAs are used to identify the segment to which a DL/I call applies. Due to the
hierarchical structure DL/I uses, you often have to specify several levels of
SSAs to access a segment at a low level in the hierarchy. An SSAList is an
ordered list of the SSAs from the Root to the Leaf. The SSAList is what is
used to make any DL/I call.
Figure 24 shows an example of creating a SSAList that will find all “Alfa” cars
made in 1989:
// Create an SSAList
SSAList modelSSAList = SSAList.createInstance();
// Construct an unqualified SSA for the Dealer segment
SSA dealerSSA = SSA.createInstance(“Dealer”);
// Construct a qualified SSA for the Model segment
SSA modelSSA = SSA.createInstance(“Model”, “CarMake”, SSA.EQUALS, “Alfa”); //
// Add an additional qualification statement
modelSSA.addQualification(SSA.AND, "CarYear", SSA.EQUALS, "1989");
// Add the SSAs to the SSAList
modelSSAList.addSSA(dealerSSA);
modelSSAList.addSSA(modelSSA);
Figure 24. Creating an SSALIST
Chapter 4. Conversational transactions 47

48 IMS Version 7 and Java Application Programming

Chapter 5. Accessing an IMS database
Before accessing an IMS database, you should have a basic understanding
of hierarchical databases. See the IMS V7 Application Programming: Design
Guide, SC26-9423-00 for more information on hierarchical databases.
In order to access information from an IMS database, you must first map the
database information in Java and then access it through a set of supported
SQL queries. This chapter explains the process of accessing IMS database
information.
5.1 Mapping an IMS database in Java classes
Mapping an IMS database in Java classes involves using the segments and
fields in the Database Definition (DBD) to create DLIDatabaseView classes
and DLISegment. The examples below use the hierarchical database found in
Figure 25. Note that the DLIDatabaseView also includes the PCB name from
the PSB generation.
Figure 25. Database view of all segments
Dealer
Model
Order Sales Stock
5.1.1 IMS DB Database Definition (DBD)
The Database Definition (DBD) is set up by the database administrator. It
defines the segments (SEGM NAME) and key fields and search fields (FIELD NAME)
of the database. Figure 26 shows the DBD for the above hierarchical
database.
© Copyright IBM Corp. 2001 49

DBD NAME=DEALERDB,ACCESS=(HDAM,OSAM),RMNAME=(DFSHDC40.1.10)
SEGM NAME=DEALER,PARENT=0,BYTES=94,
FIELD NAME=(DLRNO,SEQ,U),BYTES=4,START=1,TYPE=C
FIELD NAME=DLRNAME,BYTES=30,START=5,TYPE=C
SEGM NAME=MODEL,PARENT=DEALER,BYTES=43
FIELD NAME=(MODTYPE,SEQ,U),BYTES=2,START=1,TYPE=C
FIELD NAME=MAKE,BYTES=10,START=3,TYPE=C
FIELD NAME=MODEL,BYTES=10,START=13,TYPE=C
FIELD NAME=YEAR,BYTES=4,START=23,TYPE=C
FIELD NAME=MSRP,BYTES=5,START=27,TYPE=P
SEGM NAME=ORDER,PARENT=MODEL,BYTES=127
FIELD NAME=(ORDNBR,SEQ,U),BYTES=6,START=1,TYPE=C
FIELD NAME=LASTNME,BYTES=25,START=50,TYPE=C
FIELD NAME=FIRSTNME,BYTES=25,START=75,TYPE=C
SEGM NAME=SALES,PARENT=MODEL,BYTES=113
FIELD NAME=(SALDATE,SEQ,U),BYTES=8,START=1,TYPE=C
FIELD NAME=LASTNME,BYTES=25,START=9,TYPE=C
FIELD NAME=FIRSTNME,BYTES=25,START=34,TYPE=C
FIELD NAME=STKVIN,BYTES=20,START=94,TYPE=C
SEGM NAME=STOCK,PARENT=MODEL,BYTES=62
FIELD NAME=(STKVIN,SEQ,U),BYTES=20,START=1,TYPE=C
FIELD NAME=COLOR,BYTES=10,START=37,TYPE=C
FIELD NAME=PRICE,BYTES=5,START=47,TYPE=C
FIELD NAME=LOT,BYTES=10,START=53,TYPE=C
DBDGEN
FINISH
END
Figure 26. IMS Database Definition (DBD)
5.1.2 Mapping the DBD to DLIDatabaseView
The DLIDatabaseView class is how we define the information needed to
connect to the database. In IMS Java, the DLIDatabaseView class contains
metadata, or information about your application’s view of the database
(segments and fields) as well as the name of the database as it is known to
IMS. The database name is sufficient to make a connection, but this
metadata is also needed for processing queries.
DLIDatabaseView contains the PCBNAME= field from the PCB definition.
Following is the database name (DEALERDB) and the segment names (DEALER,
MODEL, ORDER, SALES, STOCK) extracted from the DBD in Figure 26.
50 IMS Version 7 and Java Application Programming

DBD NAME=DEALERDB,ACCESS=(HDAM,OSAM),RMNAME=(DFSHDC40.1.10)
SEGM NAME=DEALER,PARENT=0,BYTES=94,
SEGM NAME=MODEL,PARENT=DEALER,BYTES=43
SEGM NAME=ORDER,PARENT=MODEL,BYTES=127
SEGM NAME=SALES,PARENT=MODEL,BYTES=113
SEGM NAME=STOCK,PARENT=MODEL,BYTES=62
Figure 27. Sample DBD
5.1.2.1 DLIDatabaseView example
Using the extracted database name and segment names from above, we
create a DLIDatabaseView subclass called DealerDatabaseView found in
Figure 28. Notice the following:
1. Within the subclass we create an array of DLISegmentInfo objects, one
entry for each DLISegment object (see 5.1.3, “Mapping the DBD to
DLISegment” on page 52) used by the application. As you will see in the
following section about DLISegment, a DLISegment object defines the
fields in a database segment, similar to the way an IMSFieldMessage
object defines the fields in a message segment.
2. Each DLISegmentInfo object is a wrapper that associates a DLISegment
object to its parent. The parent is specified as a zero-based index in the
array.Notice that the entry for the Order segment specifies an index of 1,
which is the index in the array for the Model segment.
3. The parent of the root segment, Dealer is specified by the constant
DLIDatabaseView.ROOT to indicate that it has no parent.
4. The database name, DEALERDB, is passed in the DealerDatabaseView
constructor to the super class constructor along with the array of
DLISegmentInfo objects. Note that DEALERDB was obtained from the
PCBNAME= field from the PCB definition.
public class DealerDatabaseView extends DLIDatabaseView {
static DLISegmentInfo[] segments = { a
new DLISegmentInfo(new Dealer(), DLIDatabaseView.ROOT), c
new DLISegmentInfo(new Model(), 0),
new DLISegmentInfo(new Order(), 1), b
new DLISegmentInfo(new Sales(), 1),
new DLISegmentInfo(new Stock(), 1),
};
public DealerDatabaseView(){
super(“DEALERDB”, segments); d
}
}
Figure 28. Sample DLIDatabaseView
Chapter 5. Accessing an IMS database 51

5.1.3 Mapping the DBD to DLISegment
DLISegment is the abstract base class for objects representing segments in a
DL/I database. It allows a subclass to register the types of data stored in a
segment by providing an array of DLITypeInfo objects.
DLISegment must contain the segment name and the field names from the
DBD. Figure 29 shows the segment name and the field names extracted from
the DBD above for the DEALER segment.
SEGM NAME=DEALER,PARENT=0,BYTES=94,
FIELD NAME=(DLRNO,SEQ,U),BYTES=4,START=1,TYPE=C
FIELD NAME=DLRNAME,BYTES=30,START=5,TYPE=C
Figure 29. Dealer DBD extract
5.1.3.1 DLISegment example
Using the extracted database name and segment names from above, we
create a DLISegment subclass called Dealer (Figure 30).
public class Dealer extends DLISegment {
static DLITypeInfo[] typeInfo = { a
new DLITypeInfo(“DealerNumber”, DLITypeInfo.CHAR,1, 4,”DLRNO”),
new DLITypeInfo(“DealerName”, DLITypeInfo.CHAR,5, 30,”DLRNAME”),
new DLITypeInfo(“DealerAddress”,DLITypeInfo.CHAR,35, 50), b
new DLITypeInfo(“YTDSales”, DLITypeInfo.PACKEDDECIMAL,85, 10),
};
public Dealer() {
super(“DEALER”, typeInfo, 94); c
}
Figure 30. Sample DLISegment
In Figure 30, notice the following:
1. Within the subclass we create an array of DLITypeInfo objects, one entry
for each field used by the application.
2. Each DLITypeInfo object defines the name, type, starting offset, length,
and optionally the name of the field in the DBD. To search on a field in a
DLITypeInfo object, add the name of the field as specified in the DBD. You
can have more fields than those named in the DBD. For example the field
DealerAddress is a character field that starts at offset 35 for a length of 50
bytes and is not defined in the DBD. In order to be able to search on a
field, the field name must both be defined in the DBD file and the field
name as listed in the DBD must be provided to the DLITypeInfo object.
52 IMS Version 7 and Java Application Programming

3. The segment name, DEALER is passed in the Dealer constructor to the
super class constructor along with the array of DLITypeInfo objects and
the length of the entire array. The easiest way to calculate that length is to
add the starting offset of the last field in the array with its length and
subtract 1. In Figure 30, the length is calculated as: 85 + 10 -1 = 94.
5.2 Using JDBC to access an IMS database
The design of the database package is intended to support two styles of
database programming. The first style utilizes JDBC and provides
higher-level access designed for Java programmers who may not be familiar
with IMS. The second style is more closely associated with current IMS
application programming and provides lower-level access to most IMS
functions. Both of these mechanisms are built upon classes that the
application developer provides for defining the segments and segment
hierarchies available to the application. It is recommended to use the
higher-level style.
The lower-level access builds segment search arguments (SSAs) and calls
the functions of the DLIConnection object to read, insert, update, or delete
segments. Using this style, the application has full control to navigate the
segment hierarchy. For more details, see 4.3, “Using DLIConnection to
access a database” on page 42.
The higher-level approach utilizes a limited subset of the SQL92 query
language and JDBC 1.0, the standard Java APIs for accessing relational
databases currently supported on OS/390.
The JDBC layer is implemented using the SSA layer. That is, it parses the
SQL queries and builds SSALists to execute DL/I calls using DLIConnection.
5.2.1 Classes and field names
A database segment definition defines the fields for a set of segment
instances similar to the way a relational table defines columns for a set of
rows in a table. In this regard, segments relate to tables, and fields in a
segment relate to columns in a table.
As segments are defined in IMS Java by subclassing DLISegment, it is the
name of this DLISegment subclass that becomes the table name in an SQL
query. Similarly, as fields are defined in IMS Java using DLITypeInfo objects,
it is the name of the field passed on the DLITypeInfo constructor that is used
as the column name in an SQL query.
Chapter 5. Accessing an IMS database 53

Therefore, you can take advantage of having to name the DLISegment
subclass and DLITypeInfo object, yourself, by providing names that are
representative of the data, not necessarily the name of the segment and
fields as they exist in the database definition. In other words, by assigning
your data segment and field names aliases, you can make data retrieval more
intuitive. For example, in the query below, Model is a DLISegment subclass
that is used as a table name in the query:
SELECT * FROM Model
Note that DLISegment can contain fields not in the DBD. Searches cannot be
done unless the field is defined in the DBD.
In the following example, ModelTypeCode is the name of a DLITypeInfo
object contained in the Model segment and 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 defined
by the IMS Java programmer. They might not necessarily be the same names
used in the database definition in IMS; they just reference them.
5.2.2 Writing a JDBC application
To use JDBC to read, update, insert, and delete segment instances, an
application must:
1. Provide a subclass of DLISegment for each segment accessed in the
database that identifies the types of data stored in the segment. For an
example, see 5.1.3.1, “DLISegment example” on page 52.
2. Provide a subclass of DLIDatabaseView to identify the segments used by
an application in a database. For an example, see 5.1.2.1,
“DLIDatabaseView example” on page 51.
3. Load the DLIDriver, and retrieve a Connection object from the
DriverManager. This step is in boldface in the sample code in Figure 31.
4. Retrieve a Statement or PreparedStatement object from the Connection
and execute it. For an example, see 5.4.1, “SELECT” on page 62.
5. Iterate the ResultSet returned from the Statement or PreparedStatement
object to retrieve specific field results. For an example, see 5.4.1,
“SELECT” on page 62.
54 IMS Version 7 and Java Application Programming

The code sample in Figure 31 builds somewhat on the sample program
started in 3.3.2.3, “Subclass IMSApplication and implement main and
doBegin()” on page 37 by showing Step 3. from the list above. For examples
of each individual step, see the sample code indicated above.
Chapter 5. Accessing an IMS database 55

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 31. JDBC Application code
56 IMS Version 7 and Java Application Programming

You need imports so that the methods can be recognized by your application.
In order to access a DL/I database, use this import statement:
import com.ibm.ims.db.*;
In order to access JDBC, use this import statement:
import java.sql.*;
When using JDBC to access DL/I, an application programmer provides the
fully qualified name of the DLIDatabaseView subclass when getting a JDBC
Connection object.
When the line with Class.forName in Figure 31 above example in bold text is
executed, DLIDriver, a class in com.ibm.ims.db registers itself with the JDBC
DriverManager. When the line with DiverManager.getConnection above in bold
text is executed, the JDBC DriverManager determines which of the
registered drivers supports the supplied string. In this case, because it begins
with jdbc.dli, it locates our DLIDriver instance and requests that it create a
connection.
The following describes the JDBC 1.0 required interfaces that are
implemented in the database package. It also details limitations in the DL/I
implementation of these interfaces.
5.2.2.1 java.sql.Connection
An object that represents the connection to the database. A Connection
reference is retrieved from the DriverManager object implemented in the
java.sql package. The DriverManager obtains a Connection reference by
querying its list of registered Driver instances until it finds one that supports
the universal resource locator (URL) passed to
DriverManager.getConnection.
IMS does not support the local, connection-based commit scope defined in
the JDBC model. Therefore, the DL/I implementation of Connection.commit,
Connection.rollback, and Connection.setAutoCommit result in an
SQLException when called from a client program.
Figure 32 is the code needed to make a connection to the database.
connection = DriverManager.getConnection
(“jdbc:dli:dealership.application.DealerDatabaseView”);
Figure 32. JDBC Connection code
Chapter 5. Accessing an IMS database 57

5.2.2.2 java.sql.DatabaseMetaData
DatabaseMetaData defines a set of methods to query information about the
database, including capabilities the database might or might not support. The
class is provided for tool developers and is normally not used in client
programs. Much of the functionality is specific to relational databases and is
not implemented for DL/I databases.
5.2.2.3 java.sql.Driver
The Driver interface itself is not normally used in client programs, although
today an application needs to dynamically load a particular Driver
implementation by name. One of the first lines in a IMS JDBC program for
DL/I access must be:
Class.forName("com.ibm.ims.db.DLIDriver");
This code loads the Driver and causes the Driver implementation to register
itself with the DriverManager so that it can later be found by
DriverManager.getConnection. It is the Driver implementation that creates
and returns a Connection object to the DriverManager. The DL/I
implementation of JDBC is not fully JDBC compliant and the Driver member
jdbcCompliant returns false.
5.2.2.4 java.sql.Statement
A Statement interface is returned from Connection.createStatement. The
Statement and its subclasses PreparedStatement and CallableStatement,
define the interfaces that accept SQL statements and return tables as
ResultSet objects. The code needed to create a statement is as follows:
Statement statement = connection.createStatement();
The DL/I implementation of Statement does not support:
Named cursors, therefore the method Statement.setCursorName throws
an SQLException.
Aborting a DL/I operation, therefore Statement.cancel throws an
SQLException.
Setting a time-out for DL/I operations, therefore
Statement.setQueryTimeout and Statement.getQueryTimeout throw an
SQLException.
5.2.2.5 java.sql.ResultSet
The ResultSet interface defines an iteration mechanism for retrieving the data
in rows of a table, and for converting the data from the type defined in the
database to the type required in the application. For example,
58 IMS Version 7 and Java Application Programming

ResultSet.getString will convert an integer or decimal data type to an
instance of a Java String. The code needed to invoke ResultSet is as follows:
ResultSet results = statement.executeQuery(queryString);
Rather than building a complete set of results upon execution of a query, the
DL/I implementation of ResultSet retrieves a new segment occurrence each
time ResultSet.next is called. Further, the DL/I implementation of ResultSet
does not support:
Returning data as an ASCII stream, therefore ResultSet.getAsciiStream
throws an SQLException.
Named cursors, therefore ResultSet.getCursorName throws an
SQLException.
The method ResultSet.getUnicodeStream which is deprecated in JDBC 2.0.
5.2.2.6 java.sql.ResultSetMetaData
The interface defines methods to provide information about the types and
properties in a ResultSet object. It includes methods such as getColumnCount,
isSigned, getPrecision, and getColumnName.
5.2.2.7 java.sql.PreparedStatement
The PreparedStatement interface extends the Statement interface, adding
support for pre-compiling an SQL statement (the SQL statement is provided
at construction instead of execution) and for substituting values in the SQL
statement (“UPDATE Suppliers SET Status = ? WHERE City = ?”).
5.2.2.8 java.sql.CallableStatement
The CallableStatement interface extends the Statement interface and
supports calling stored procedures in a database. DL/I does not currently
support stored procedures, therefore the DLIDatabaseMetaData method
supportsStoredProcedures returns false and the Connection method
prepareCall throws an SQLException. Therefore there currently is no way for a
DL/I JDBC application to create a CallableStatement object. All exceptions
thrown from the JDBC APIs are of type SQLException, or a class derived
from SQLException. An SQLException thrown by the DLI JDBC driver contains:
An NLS-enabled text string describing the error.
An “SQLState” string identifying the exception that conforms to the
X/Open SQLState conventions.
An error code containing the failing DLI status code if one is available. If a
status code is not available or the error is unrelated to a DLI call, the error
code is zero.
Chapter 5. Accessing an IMS database 59

5.3 Supported data types in IMS Java
IMS Java supports the JDBC types specified in Table 1.
Table 1. Supported data types
JDBC type Java type
CHAR string
VARCHAR string
BIT byte
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
TIMESTAMP java.sql.Timestamp
60 IMS Version 7 and Java Application Programming

Table 2 shows the available get methods for accessing data of a certain JDBC
type.
Table 2. Available get methods for data types
JDBC Type
TINYINT
SMALLINT
INTEGER
BIGINT
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
FLOAT
DOUBLE
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
Those marked with “X” indicate methods designed for accessing the given
data type. No truncation or data loss will occur using those methods. Those
marked with “O” indicate all other legal calls; however, data integrity cannot
be ensured using those methods. If the box is empty (it neither contains an
“X” or an “O”), using that method for a data type will result in an exception.
BIT
CHAR
VARCHAR
PACKEDDECIMAL
ZONEDECIMAL
BINARY
DATE
TIME
TIMESTAMP
Chapter 5. Accessing an IMS database 61

Note
At this time PackedDecimal and ZoneDecimal data types DO NOT support
the Sign Leading or Sign Seperate modes. Sign information is always
stored with the Sign Trailing method.
5.4 Supported SQL grammar
IMS Java does not support aggregate keywords. The SQL keywords in Table
3 are the only keywords currently supported in IMS Java:
Table 3. Supported SQL keywords
ALL AND DELETE DISTINCT
FROM INSERT INTO OR
SELECT SET UPDATE VALUE
VALUES WHERE
5.4.1 SELECT
A SELECT statement is a query used as a top-level SQL statement. Figure 33
shows an example that uses the results of a SELECT query to update
modelOutput with the model information. It requires an inputMessage with the
ModelTypeCode.
62 IMS Version 7 and Java Application Programming

5.4.2 FROM
public boolean getModelDetails(InputMessage inputMessage,
ModelOutput modelOutput) throws IMSException {
}
}
// Parse the input message for ModelTypeCode
String queryString = “SELECT * from Model where ModelTypeCode = “
+ “‘” + inputMessage.getString(“ModelTypeCode”).trim() + “‘”;
// Create a statment and execute it to get a ResultSet
try {
Statement statement = connection.createStatement();
ResultSet results = statement.executeQuery(queryString);
// Send back the result of the query
// Note: since "ModelTypeCode" is unique - only 1 row
// is returned
if (results.next()) {
modelOutput.setString(“ModelTypeCode”,
results.getString(“Type”).trim());
modelOutput.setString("Make",
results.getString(“Make”).trim());
modelOutput.setString(“Model”,
results.getString(“Model”));
modelOutput.setString(“Year”,
results.getString(“Year”));
modelOutput.setString(“CityMiles”,
results.getString(“EPACityMileage”));
modelOutput.setString(“HighwayMiles”,
results.getString(“EPAHighwayMileage”));
modelOutput.setString(“Price”,
results.getString(“Price”));
modelOutput.setString(“Horsepower”,
results.getString(“Horsepower”));
return true;
}
else {
reply(“Unknown Type”);
return false;
}
}
catch (SQLException e) {
reply(“Query Failed:”+ e.toString());
return false;
}
Figure 33. Example of a SELECT statement
In standard SQL, the FROM clause can contain a list of table names separated
by commas. This will result in a “join” of the tables in the list based on the
equality of specified column values of the joined tables. An IMS DL/I
database is hierarchical, so a join is implied, and only the segment furthest
down the hierarchy needs to be specified in the FROM clause, even though
Chapter 5. Accessing an IMS database 63

fields in all segments in the path can be named in the WHERE or SELECT clause.
In Figure 34, the two queries are equivalent.
SELECT CarModel
FROM Model
WHERE CarYear=’2000’
SELECT Model.CarModel
FROM Model
WHERE Model.CarYear=’2000’.
Figure 34. Example of a FROM statement
In IMS Java, you only specify the segment furthest down the hierarchy in the
FROM clause. You can query different segments by preceding the field name
with the segment name, as in Figure 35.
SELECT Dealer.DealerName,CarModel
FROM Model
WHERE CarMake=’Ford’
Figure 35. FROM statement in Dealer code
5.4.3 UPDATE
An UPDATE statement modifies the value of at least one segment occurrence.
An UPDATE statement applies its SET clause to each row in the specified table
with a WHERE clause set for TRUE. If the UPDATE statement does not have a WHERE
clause, the SET clause is applied to all rows in the specified table.
A SET clause contains at least one assignment. In each assignment, the
values to the right of the equal sign are computed and assigned to columns to
the left of the equal sign. For example, the UPDATE statement in Figure 36 is
called to accept an order. When a customer accepts an order, the car’s
SerialNo and delivery dates are filled in.
String updateString = “UPDATE Order “
+ “SET SerialNo = ‘”
+ inputMessage.getString(“StockVINumber”).trim()
+ “‘, “
+ “DeliverDate = ‘”
+ inputMessage.getString(“Date”).trim()
+ “© WHERE OrderNumber = ‘”
+ inputMessage.getString(“OrderNumber”).trim()
+ “‘”;
Figure 36. Example of an UPDATE statement
64 IMS Version 7 and Java Application Programming

It is possible for an update to violate some constraint, such as a check
constraint or a foreign key constraint. If this or any other error occurs during
the execution of an UPDATE statement, the statement is rolled back and no
update is performed.
5.4.4 DELETE
The DELETE statement in IMS Java deletes at least one segment occurrence.
The DELETE statement removes the segment occurrences specified in the
WHERE clause. If no WHERE clause is specified, all of the segment occurrences
are deleted. It is possible that deleting some of the occurrences that are
specified in the DELETE statement may violate some constraint. In that case,
the statement is rolled back and no occurrences are deleted. Figure 37 shows
an example of a DELETE statement.
String updateString = “DELETE from Order where “
+ “Dealer.DealerNumber = ’”
+ dealerDesired+ “‘ AND “
+ “OrderNumber = ‘” + orderDesired + “‘”;
try {
Statement statement = connection.createStatement();
int results = statement.executeUpdate(updateString);
...
}
catch (SQLException e) {
...
}
Figure 37. Example of a DELETE statement
5.4.5 INSERT
The INSERT statement inserts at least one row into a table. All column names
must be in the statement; there are no default values in this release. Figure
39 is an example of an INSERT statement which inserts a field in the
database:
5.4.6 How IMS Java has extended SQL
Standard SQL does not have a WHERE clause in an INSERT statement, as
tuples are just being inserted into the table specified after the INTO keyword.
In an IMS DL/I database, we are actually inserting a new instance of the
specified segment, so we need to know where in the database this segment
occurrence needs to be placed. In the case of an INSERT statement, the
WHERE clause is necessary in all cases except when inserting a root
segment. In the case of a prepared statement, the list of values can have a ?
Chapter 5. Accessing an IMS database 65

5.4.7 Statement
as the value, that can be substituted before the statement is executed.
Examples are shown in Figure 38 and Figure 39.
INSERT INTO Model(ModelTypeCode, CarMake, CarModel, CarYear,
Price, EPACityMileage, EPAHighwayMileage, Horsepower)
VALUES (?,?,?,?,?,?,?,?)
WHERE Dealer.DealerNumber=?.
Figure 38. Example of WHERE and INSERT
String insertString = “INSERT INTO Sales “
+ “(DateSold, PurchaserLastName, PurchaserFirstName, “
+ “PurchaserAddress, SoldBy, StockVINumber)”
+ “ VALUES (‘07032000’, ‘Beier’, ‘Otto’, “
+ “’101 W. 1st Street, Smalltown, CA’, “
+ “’S123’’1ABCD23E4F5678901234’) “
+ “WHERE Dealer.DealerNumber = ’A123’”
+ “‘ AND ModelTypeCode = ‘K1’)”;
Figure 39. Example of an INSERT statement
A JDBC statement object represents one SQL statement. A statement can be
run immediately or it can be prepared once and then run several times with
different parameters.
5.4.8 Prepared statement
A prepared statement is a statement that is written once with variable
parameters to be run multiple times. Before a prepared statement can be run,
values must be provided for all of the parameter markers in the statement.
66 IMS Version 7 and Java Application Programming

Part 2. Sample application
This part of the book describes a sample IMS Java application.
It contains the following chapters:
Chapter 6, “IMSAuto application build and execute” on page 69
Chapter 7, “VisualAge for Java IMS application development” on page 119
© Copyright IBM Corp. 2001 67

68 IMS Version 7 and Java Application Programming

Chapter 6. IMSAuto application build and execute
To run your Java programs under IMS V7, first you have to code or generate
the Java code for your application, compile the Java source code into Java
bytecode, and bind the Java bytecode into an IMS executable program using
the ET/390 HPJ compiler. You can use an editor to code your Java programs,
or you can generate your Java source code using a GUI Java development
tool such as VisualAge for Java.
Figure 40 illustrates the IMS Java application development scenario for IMS.
VisualAge for Java,
Enterprise Enterprise Edition
Edit/Compile
Edit/Compile
Browse Browse
Version Version Control
Error Error Feedback Feedback
Local
Debugger
Remote Remote
Debugger Debugger
Profiler Profiler
J
P
O
R
T
Export Export
Java Java
Bytecode
IMS
Java
Figure 40. IMS Java application development scenario
High
Performance
Compiler
Executable
Run on
OS/390
Trace Trace
OS/390
The HPJ compiler runs on the OS/390 mainframe and can be invoked by
running JCL under MVS or by using the UNIX System Services hpj command
on an ET/390 workstation. Typically, whether using a batch JOB or working
interactively, you will run from a makefile or a script.
© Copyright IBM Corp. 2001 69
PC Se rver
320

6.1 Testing IMS applications
Initially we used one of the IMS IVP programs to familiarize ourselves with
the UNIX System Services environment, the JDK javac compiler, the ET/390
HPJ compiler, and the IMS Java Application Programming Interfaces
(JavaToDLI and JDBC IMS). For comparison purposes, we had three
versions of source code for the IVP program: original COBOL code, Java
code using the SSAs and DLIConnection interface, and Java code using
JDBC IMS. Throughout the remainder of the project we worked with a more
involved Java application, called Auto Dealership, to test and illustrate our
findings. This application accesses the IMS message queue and IMS
databases using the JDBC IMS interface.
Source code for the sample applications referenced in this redbook can be
found in the appendices referenced in Table 4.
Table 4. References to source code
Application Tran Code Java To DLI JDBC COBOL
IVP Telephone IVTCC Appendix E,
“IVP
application —
Java source
(Java to DLI
version)” on
page 311
IVP Telephone IVTCC Appendix F,
“IVP
application —
Java source
(JDBC
version)” on
page 325
IVP Telephone IVTCC Appendix G,
“IVP
application —
COBOL
source” on
page 339
Auto Dealership IMSAUTO Appendix I,
“Dealership
sample
application”
on page 357
70 IMS Version 7 and Java Application Programming

6.2 “Nonvisual” IMS application development
Your manually coded Java programs can reside on either the mainframe or
the workstation. Your IMS Java programs can make use of both the JDK
Class Libraries (see reference) and the IMS Java Class Libraries (see
Appendix A IMS JAVA Packages). They can be compiled into bytecode using
the JDK javac compiler on the workstation or the mainframe. The HPJ
compiler resides on the mainframe, so when you use the workstation you
have to transfer the bytecode to the mainframe. In this section, we focus on
doing as much as possible under MVS, either in TSO or with batch jobs. This
will enable you to integrate Java program development into your existing
change control system in use on the mainframe host system. It is also useful
to simply set up some batch jobs for often repeated tasks such as compiling,
linking, and copying to an IMS PDSE PGMLIB.
6.2.1 Some TSO/E commands
In this section, we describe the Time Sharing Option Extensions (TSO/E)
commands that you use to invoke the UNIX System Services shell and the
TSO/E commands that you can use to work with the HFS file system.
The commands for working with the HFS file system are:
Start a shell
– ISHELL Invokes the UNIX System Services ISPF shell.
– OSHELL Invokes BPXBATCH from TSO/E.
– OMVS Invokes the UNIX System Services shell.
– BPXBATCH Runs shell commands, shell scripts, or
executable files.
Edit or browse an HFS file
– OBROWSE Browses an HFS file.
– OEDIT Edits an HFS file.
Copy a file
– OCOPY Copies an MVS data set member or HFS file to
another member or file
– OGET and OGETX Copy HFS files from a directory to an MVS PDS
or PDSE
– OPUT and OPUTX Copy members from an MVS PDS or PDSE to
an HFS directory
Chapter 6. IMSAuto application build and execute 71

You can enter the above TSO/E commands from:
TSO/E
ISPF option 6 (Interactive System Productivity Facility command
processor panel)
The shell
Note
Enter TSO/E commands from an ISPF panel that does not convert all
the parameters into upper case; some panels, such as the main ISPF
panel, convert your input into upper case. Using ISPF Option 6 is
preferable, because it does not convert into upper case the commands
that you enter, (remember: the UNIX System Services environment is
case-sensitive).
The path name is relative to the working directory (usually the HOME
directory) of the TSO/E session, not the shell session.
Use absolute path names when entering any TSO/E commands.
Avoid using spaces or single quotes within path names.
In the sections that follow, we assume that you are using the ISPF Command
Shell (option 6 on the ISPF menu) as shown in Figure 41.
72 IMS Version 7 and Java Application Programming

Menu List Mode Functions Utilities Help
------------------------------------------------------------------------------------
ISPF Command Shell
Enter TSO or Workstation commands below:
===>
Place cursor on choice and press enter to Retrieve command
=> ishell
=> listenq
=> ftp 9.112.127.108
=> receive
=> xmit stlmvs1.H044381 dsn(ITSO.SMPE.SYSOUT)
=> omvs
=> omvsd
=> omvds
=> oshell
=> ommvs
Figure 41. ISPF Command Shell panel
On this panel you can enter the commands on the first line. The 10 most
recent commands are stored on the lower 10 lines. To retrieve a stored
command, move the cursor to the line and press Enter. The command is
moved to the first line and can be edited if necessary. Press Enter again to
execute the command.
6.3 ISHELL: Invoking UNIX System Services
We found ISHELL to be the most useful command for working with HFS files.
ISHELL invokes the UNIX System Services ISPF shell, a panel interface that
helps you set up and manage UNIX System Services functions. You can use
the ISHELL command to:
List the contents of a directory.
Display the attributes of a file.
Display the attributes and contents of a symbolic link (syml).
Delete directory, a file, a symbolic link or a special file.
Rename a directory, a file, a symbolic link or a special file.
Edit a file.
Browse a file as text or records.
Copy a file or an entire directory.
Chapter 6. IMSAuto application build and execute 73

Replace a file.
Print a file or an entire directory.
Compare two files or directories.
Find search string(s) in a file or a directory.
Run an executable file.
Display the file system attributes.
Create an HFS.
Mount and unmount an HFS.
Set the working directory.
Set up character-special files.
Set up standard directories for a root file system.
Set up existing users and groups for UNIX System Services access.
Tasks such as mounting, unmounting, setting up character-special files, and
setting up existing users and groups for UNIX System Services access
require either superuser authority or the RACF SPECIAL attribute.
Field level and panel help are available throughout the dialog via PF1. For
additional information on ISHELL, see the OS/390 UNIX System Services
User’s Guide, SC28-1891, and the online help panels.
Your HOME directory as defined in your RACF profile OMVS segment is used
as the default path name when the shell starts up (see Figure 42). You can
specify any path name or command on this panel. We also found the tool bar
at the top of the this panel to be very useful.
74 IMS Version 7 and Java Application Programming

File Directory Special_file Tools File_systems Options Setup Help
-------------------------------------------------------------------------------------
OpenMVS ISPF Shell
Enter a pathname and do one of these:
- Press Enter.
- Select an action bar choice.
- Specify an action code or command on the command line.
Return to this panel to work with a different pathname.
More: +
/u/imsres4
_____________________________________________________________________
_____________________________________________________________________
_____________________________________________________________________
Command ===> ____________________________________________________________________
Figure 42. ISHELL main screen
Press Enter to get the file list of the directory you entered (see Figure 43).
Chapter 6. IMSAuto application build and execute 75

Figure 43. ISHELL Directory List
Here you can issue your commands by entering the specific action code. Or
you can issue commands using the general action character ‘/’ and then from
the following Select an Action panel, entering the number that corresponds to
the desired action (see Figure 44 for files and Figure 45 for directories).
76 IMS Version 7 and Java Application Programming
Directory List
/u/imsres4/
Select one or more files with / or action codes.
Type Filename Row 1 of 59
_Dir .
_Dir ..
_ File .profile
_ Dir ceedumps
_Dir com
_ File Dealerhpj.sh.standalone
_ File Dealerhpj.sh.ver1
_ File Dealerhpj.sh.ver3
_ File Dealerjavac.sh.ver1
_ File Dealerjavac.sh.ver2
_ File Dealerjavac.sh.ver3
_ File Dealerscript.ver1
_ File Dealerscript.ver3
_ Dir dealership
_ File Dealertest.sh.ver1
_ File exechpj.sh.ver1
_ File execjavac.sh.ver1
Command ===> ________________________________________________________________________

Select an Action
Enter a number to select an action for the file:
/u/imsres4/Dealerscript.ver3
__ 1. Not available
2. Attributes(A)...
3. Delete(D)...
4. Rename(R)...
5. Edit(E)...
6. Browse text(B)...
7. View records(V)...
8. Copy to(C)...
9. Replace From(I)...
10. Print(P)
11. Compare(M)...
12. Find(F)...
13. Run(X)...
14. Not available
15. File system(U)
Figure 44. ISHELL Select an Action panel for files
Select an Action
Enter a number to select an action for the directory:
/u/imsres4/dealership
__ 1. List Directory(L)...
2. Not available
3. Attributes(A)...
4. Delete(D)...
5. Rename(R)...
6. Copy to PDS(C)...
7. Copy from PDS(I)...
8. Print(P)
9. Compare(M)...
10. Find(F)...
11. Set working directory(W)
12. File system(U)
Figure 45. ISHELL Select an Action panel for directories
To move to another directory, use the ‘L’ or ‘/’ and option 1 on the entry field
next to the directory to which you want to move. To move up one directory
level, use the ‘..’ directory entry.
Chapter 6. IMSAuto application build and execute 77

To copy a file, use ‘C’ or ‘/’ and option 8 on the entry field next to the file you
want to copy. A panel on which you can specify the destination of the file then
pops up.
To browse or edit a file, use ‘B’ or ‘E’ respectively. The browser/editor is the
same as that which is invoked by ISPF option 1, 2, 3, 4, OBROWSE, or
OEDIT.
To display the attributes of a file, use ‘A’ or ‘/’ and option 2 on the entry field
next to the file. The display will contain file permissions, size, various dates
and other information as seen in Figure 46.
Edit Help
------------------------------------------------
Display File Attributes
Pathname : /u/imsres4/Dealerhpj.sh.standalone
More: +
Filetype ....:Regularfile
Permissions . . . : 700
Filesize ....:1192
Fileowner....:RCONWAY(0)
Group owner . . . : SYS1(0)
Last modified . . : 08/14/2000 18:44 GMT
Lastchanged...:08/14/200018:44GMT
Last accessed . . : 08/29/2000 17:26 GMT
Created .....:08/10/200016:50GMT
Linkcount....:1
Set UID bit . . . : 0
Figure 46. Display File Attributes option
78 IMS Version 7 and Java Application Programming

6.4 OSHELL: Invoking BPXBATCH from TSO/E
The OSHELL command uses BPXBATCH to run a single shell command or
shell script. For example, to display all files in your HOME directory, enter
oshell ls -l
The result is shown on one or more TSO panels, separated by three asterisks
(***) in Figure 47, Figure 48, and Figure 49).
Menu List Mode Functions Utilities Help
-------------------------------------------------------------------------
Enter TSO or Workstation commands below:
===> oshell ls -l
Place cursor on choice and press enter to Retrieve command
=> oshell ls -l
=> ishell
=> listc
=> omvs
=> receive
=> oshell
=> listenq
=> ftp 9.112.127.108
=> xmit stlmvs1.H044381 dsn(ITSO.SMPE.SYSOUT)
LIBPATH reset to /lib:/usr/lib:/usr/lpp/db2/db2610/lib:
----------------------------------------------------
Set up environment variables for Java for MVS
***
Figure 47. OSHELL ls -l input
Chapter 6. IMSAuto application build and execute 79

----------------------------------------------------
----------------------------------------------------
Previous environment for Java unset
Previous JAVA_HOMEenvironment set to /usr/lpp/java18/J1.1
for Java unset
JAVA_HOME PATH reset set to to /usr/lpp/java18/J1.1/bin:/usr/lpp/db2/db2610/bin:/bin:.
/usr/lpp/java18/J1.1
PATH ----------------------------------------------------
reset to /usr/lpp/java18/J1.1/bin:/usr/lpp/db2/db2610/bin:/bin:.
----------------------------------------------------
CLASSPATH set to .:/usr/lpp/internet/server_root/cgi-bin/icsclass.zip:/usr/lpp/
internet/server_root/servlets/public:/usr/lpp/java18/J1.1/lib/RACF.jar:/usr/lpp/
CLASSPATH set to .:/usr/lpp/internet/server_root/cgi-bin/icsclass.zip:/usr/lpp/
internet/server_root/servlets/public:/usr/lpp/java18/J1.1/lib/RACF.jar:/usr/lpp/
db2/db2610/classes/db2sqljclasses.zip:/usr/lpp/java18/J1.1/lib/classes.zip:/usr/
db2/db2610/classes/db2sqljclasses.zip:/usr/lpp/java18/J1.1/lib/classes.zip:/usr/
lpp/db2/db2610/c
lpp/db2/db2610/c
LD_LIBRARY_PATH reset to .:/usr/lpp/db2/db2610/bin:/usr/lpp/db2/db2610/lib:/usr
/lpp/java18/J1.1/lib/mvs/native_threads
LD_LIBRARY_PATH reset to .:/usr/lpp/db2/db2610/bin:/usr/lpp/db2/db2610/lib:/usr
/lpp/java18/J1.1/lib/mvs/native_threads
STEPLIB set to DB2V610J.SDSNEXIT:DSN610.SDSNEXIT:DSN610.SDSNLOAD:HPJ390.SHPJMOD
:HPJ390.SHPOMOD:CEE.SCEERUN:EQAW.V1R2M0.SEQAMOD
STEPLIB set to DB2V610J.SDSNEXIT:DSN610.SDSNEXIT:DSN610.SDSNLOAD:HPJ390.SHPJMOD
:HPJ390.SHPOMOD:CEE.SCEERUN:EQAW.V1R2M0.SEQAMOD
DB2SQLJPROPERTIES set to /usr/lpp/db2/db2610/classes/db2sqljjdbc.properties
DB2SQLJPROPERTIES DB2SQLJDBRMLIB set set to to DB2V610J.DBRMLIB.DATA
/usr/lpp/db2/db2610/classes/db2sqljjdbc.properties
DB2SQLJDBRMLIB java version “1.1.8” set to DB2V610J.DBRMLIB.DATA
java hpjava version version “1.1.8” “VisualAge 2.0 CL4.1 - May 26 2000”
hpjava *---------------------------------------------------------------
version “VisualAge 2.0 CL4.1 - May 26 2000”
*--------------------------------------------------------------profile
executed for HPJ, JAVA and SQLJ
*--------------------------------------------------------------profile
executed for HPJ, JAVA and SQLJ
*--------------------------------------------------------------total
336
total drw------- 336 2 AAAAAAA DB2RES 8192 Jul 20 19:15 IBMVJava
drw------- drwxr-xr-x 26 AAAAAAA DB2RES 8192 Jul Dec 206 19:15 1999 IBMVJava SYSTEM
drwxr-xr-x *** 6 AAAAAAA DB2RES 8192 Dec 6 1999 SYSTEM
***
Figure 48. OSHELL ls -l output: Panel 1
drwxr-xr-x 4 AAAAAAA DB2RES 32768 Jun 14 05:37 bin
lrwxrwxrwx 1 AAAAAAA DB2RES 12 Feb 3 2000 dev -> $SYSNAME/dev
drwxr-xr-x 13 AAAAAAA DB2RES 8192 Aug 25 14:16 etc
drw------- 2 AAAAAAA DB2RES 8192 Jul 20 18:33 extras
drw------- 2 AAAAAAA DB2RES 8192 Jul 20 18:34 ibmvjava
drwxr-xr-x 2 AAAAAAA DB2RES 8192 May 22 11:01 imsjava
lrwxrwxrwx 1 AAAAAAA DB2RES 16 Feb 3 2000 krb5 -> etc/dce/var/krb5
drwxr-xr-x 2 AAAAAAA DB2RES 8192 Jun 14 05:37 lib
drwxr-xr-x 2 AAAAAAA DB2RES 8192 Jun 14 05:37 opt
-rwx------ 1 AAAAAAA DB2RES 288 Jul 19 18:52 profile.imsjava
-rwx------ 1 AAAAAAA DB2RES 1132 Jul 21 14:08 profile.imsres1
drwxr-xr-x 4 AAAAAAA DB2RES 8192 Jun 14 05:37 samples
drwxr-xr-x 11 AAAAAAA SYS1 8192 Aug 1 06:28 servils1
drwxr-xr-x 3 AAAAAAA DB2RES 8192 Aug 28 12:41 servils1_db2v6
drwxr-xr-x 2 AAAAAAA DB2RES 8192 Aug 28 13:32 servils1_r9
lrwxrwxrwx 1 AAAAAAA DB2RES 12 Feb 3 2000 tmp -> $SYSNAME/tmp
drwxr-xr-x 29 AAAAAAA SYS1 8192 Aug 30 17:50 u
drwxr-xr-x 10 AAAAAAA DB2RES 8192 Jun 14 05:37 usr
lrwxrwxrwx 1 AAAAAAA DB2RES 12 Feb 3 2000 var -> $SYSNAME/var
drwxr-xr-x 4 AAAAAAA DB2RES 8192 Jun 28 12:47 was
drwxr-xr-x 4 AAAAAAA DB2RES 8192 Jun 28 12:47 web
THE RECORD SIZE IN THE OUTPUT DATA SET IS SMALLER THAN A LINE IN THE INPUT FILE
. SOME RECORDS HAVE BEEN TRUNCATED.
***
Figure 49. OSHELL ls -l output: Panel 2
80 IMS Version 7 and Java Application Programming

When you use OSHELL, do not use an ampersand (&) to run a shell
command in the background. You can use the OSHELL command to:
List files in a directory
Create, delete, or rename a directory, file, or special file
Display contents of a file
Copy a file
Display a files attributes
Search files for text strings
Compare files or directories
Run an executable file
Display the attributes and contents of a symbolic link (syml)
Set up character-special files
Set up standard directories for a root file system
Some of these tasks may require superuser authority.
6.5 OMVS: Invoking the UNIX System Services shell
If you want to issue several UNIX System Services shell commands, you can
invoke OMVS. The shell starts up in your HOME directory (see Figure 50).
IBM
Licensed Material - Property of IBM
5647-A01 (C) Copyright IBM Corp. 1993, 2000
(C) Copyright Mortice Kern Systems, Inc., 1985, 1996.
(C) Copyright Software Development Group, University of Waterloo, 1989.
All Rights Reserved.
U.S. Government users - RESTRICTED RIGHTS - Use, Duplication, or
Disclosure restricted by GSA-ADP schedule contract with IBM Corp.
IBM is a registered trademark of the IBM Corp.
LIBPATH reset to /lib:/usr/lib:/usr/lpp/db2/db2610/lib:
----------------------------------------------------
Set up environment variables for Java for MVS
----------------------------------------------------
Previous environment for Java unset
JAVA_HOME set to /usr/lpp/java18/J1.1
PATH reset to /usr/lpp/java18/J1.1/bin:/usr/lpp/db2/db2610/bin:/bin:.
===>
MORE...
ESC=¢ 1=Help 2=SubCmd 3=HlpRetrn 4=Top 5=Bottom 6=TSO
7=BackScr 8=Scroll 9=NextSess 10=Refresh 11=FwdRetr 12=Retrieve
Figure 50. OMVS startup panel
Chapter 6. IMSAuto application build and execute 81

You can then issue UNIX System Services commands, for example, ls -l,
to list your directory. In contrast to the OSHELL command, everything is
displayed at once when you use the OMVS command. Therefore, after the
command completes, you see the panel in Figure 51 first. You can then use
PF7 to browse backwards, to get to the panel in Figure 52. Using PF8 you
can browse forward again. Unlike the OSHELL command, where the output
disappears after you press the Enter key, the output of OMVS is kept for
browsing. OMVS can be customized. See the OS/390 UNIX System Services
Command Reference, SC28-1892, for further details.
-rw-r--r-- 1 RCONWAY SYS1 5172 Aug 14 13:10 JAVADUMP.20000814.131025.8
3887243
-rw-r--r-- 1 RCONWAY SYS1 5718 Aug 14 14:35 JAVADUMP.20000814.143505.8
3887247
-rwx------ 1 RCONWAY SYS1 1186 Jul 27 21:08 TPCChpj.sh.ver1
-rwx------ 1 RCONWAY SYS1 316 Jul 27 21:07 TPCCjavac.sh.ver1
-rwx------ 1 RCONWAY SYS1 414 Jul 27 21:07 TPCCscript.ver1
-rwx------ 1 RCONWAY SYS1 413 Aug 8 18:04 Testscript.ver1
drw------- 2 RCONWAY SYS1 8192 Aug 30 18:39 ceedumps
drwxr-x--x 3 RCONWAY SYS1 8192 Aug 10 18:56 com
drwxrwxr-x 11 RCONWAY SYS1 8192 Aug 25 12:45 dealership
-rwx------ 1 RCONWAY SYS1 972 Jul 25 12:23 exechpj.sh.ver1
-rwx------ 1 RCONWAY SYS1 320 Jul 25 12:22 execjavac.sh.ver1
-rwx------ 1 RCONWAY SYS1 1282 Jul 24 12:28 profile
-rwx------ 1 RCONWAY SYS1 308 Jul 24 12:20 profile.imsjava
-rwx------ 1 RCONWAY SYS1 1517 Aug 29 17:07 profile.imsres4
-rwx------ 1 RCONWAY SYS1 633 Jul 25 17:42 runit.sh.new
-rwx------ 1 RCONWAY SYS1 633 Jul 24 18:09 runit.sh.v1
drwxrwxr-x 3 RCONWAY SYS1 8192 Aug 25 21:30 samples
IMSRES4 @ SC47:/u/imsres4>
===>
INPUT
ESC=¢ 1=Help 2=SubCmd 3=HlpRetrn 4=Top 5=Bottom 6=TSO
7=BackScr 8=Scroll 9=NextSess 10=Refresh 11=FwdRetr 12=Retrieve
Figure 51. OMVS ls -l output: Panel 1
82 IMS Version 7 and Java Application Programming

IMSRES4 @ SC47:/u/imsres4>ls -l
total 976
-rwx------ 1 RCONWAY SYS1 1192 Aug 14 14:44 Dealerhpj.sh.standalone
-rwx------ 1 RCONWAY SYS1 1198 Aug 9 18:02 Dealerhpj.sh.ver1
-rwx------ 1 RCONWAY SYS1 1195 Aug 14 12:50 Dealerhpj.sh.ver3
-rwx------ 1 RCONWAY SYS1 1348 Aug 8 19:14 Dealerjavac.sh.ver1
-rwx------ 1 RCONWAY SYS1 1743 Aug 9 19:21 Dealerjavac.sh.ver2
-rwx------ 1 RCONWAY SYS1 1707 Aug 10 16:07 Dealerjavac.sh.ver3
-rwx------ 1 RCONWAY SYS1 542 Aug 9 17:10 Dealerscript.ver1
-rwx------ 1 RCONWAY SYS1 597 Aug 10 20:58 Dealerscript.ver3
-rwx------ 1 RCONWAY SYS1 926 Aug 8 18:12 Dealertest.sh.ver1
-rw-r--r-- 1 RCONWAY SYS1 28914 Aug 25 15:14 IMSAUTO.map
-rw-r--r-- 1 RCONWAY SYS1 2025 Aug 25 15:14 IMSAUTO.syslin
===>
MORE...
ESC=¢ 1=Help 2=SubCmd 3=HlpRetrn 4=Top 5=Bottom 6=TSO
7=BackScr 8=Scroll 9=NextSess 10=Refresh 11=FwdRetr 12=Retrieve
Figure 52. OMVS ls -l output: Panel 2
6.6 BPXBATCH: Shell commands, shell scripts, or executable files
BPXBATCH makes it easy for you to run shell scripts or OS/390 executable
files that reside in HFS files. You can run from your TSO/E session or from
batch. You can allocate MVS standard files stdin, stdout, stderr as HFS files
for passing any input to be processed with shell commands, for writing
output, and for error messages. Always allocate stdin as READ; always
allocate stdout and stderr as WRITE. Such standard files must be HFS files.
You allocate them by specifying the PATH keyword option on the ALLOCATE
command. If you do not allocate them, they default to /dev/null, the output is
discarded, and you get end of file on input files. A program run by
BPXBATCH cannot use allocations for any files other than stdin, stdout, or
stderr.
BPXBATCH takes the following parameters: SH or PGM. These parameters
specify whether BPXBATCH is to run a shell script or command versus an
OS/390 executable file located in an HFS file. If neither SH nor PGM is
specified, BPXBATCH assumes that the shell is to be started to run the shell
script allocated by stdin.
SH specifies the shell that is to be started to run shell commands or scripts
provided from stdin. If SH is specified without a script, command or
program_name, BPXBATCH attempts to run anything read in from stdin.
SH is the default.
Chapter 6. IMSAuto application build and execute 83

PGM specifies the program_name that is to be run as a called program from
a shell environment. If you specify PGM, you must also specify
program_name. BPXBATCH creates a process for the program to run in and
then calls the program. If possible, the HOME and LOGNAME environment
variables are set when the program is run.
program_name specifies the shell command name or the HFS pathname for
the shell script or OS/390 executable file that you want to run. program_name
can also contain option information. program_name is in upper case and
lower case letters. When PGM and program_name are specified and the
specified program name does not begin with a slash character (/),
BPXBATCH prefixes the user’s initial working directory information to the
program path name.
For example, from TSO/E:
If you want to run the shell script you specify with stdin, you have to enter
the following two lines:
ALLOCATE FILE(STDIN) PATH(‘/u/imsres4/Dealerscript.ver3’)PATHOPTS(ORDONLY)
BPXBATCH SH
If you want to run the program test_program, you have to enter the
following line:
BPXBATCH PGM /u/imsres4/test_program
If you want to run the shell Dealerscript.ver3 script and put its output in the
test.out file in a temporary directory, you have to enter the following line:
BPXBATCH SH /u/imsres4/Dealerscript.ver3’> /tmp/test.out
BPXBATCH can also be called in a batch job where the same restrictions as
those given above for TSO/E apply. Figure 53 shows the batch job JCL that
we used.
84 IMS Version 7 and Java Application Programming

AUTOHPJ JOB (999,POK),’ITSO IMS TEAM’,MSGCLASS=U,CLASS=A,
// NOTIFY=&SYSUID,TIME=1440,REGION=0M
//* ------------------------------------------------------------------
//* EXECUTE SCRIPT
//* ------------------------------------------------------------------
//UXCALL EXEC PGM=BPXBATCH,REGION=0M,
// PARM=’SH /u/imsres4/Dealerscript.ver3’
//STEPLIB DD DISP=SHR,DSN=CEE.SCEERUN
//STDENV DD DUMMY
//STDIN DD DUMMY
//************************************* THE OUTPUT *********
//STDOUT DD PATH=’/u/imsres4/&SYSUID..autohpj.a082500.eout’,
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),PATHMODE=SIRWXU
//************************************* THE ERRORS *********
//STDERR DD PATH=’/u/imsres4/&SYSUID..autohpj.a082500.eerr’,
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),PATHMODE=SIRWXU
//************************************* THE SYSOUT *********
//SYSPRINT DD SYSOUT=*
//* ------------------------------------------------------------------
//* COPY RESULT(HFS) TO SYSOUT
//* ------------------------------------------------------------------
//HFS2PRT EXEC PGM=IKJEFT01,DYNAMNBR=300,COND=EVEN
//SYSTSPRT DD SYSOUT=*
//HFSOUT DD PATH=’/u/imsres4/&SYSUID..autohpj.a082500.eout’
//HFSERR DD PATH=’/u/imsres4/&SYSUID..autohpj.a082500.eerr’
//STDOUTL DD SYSOUT=*,DCB=(RECFM=VB,LRECL=6140,BLKSIZE=0)
//STDERRL DD SYSOUT=*,DCB=(RECFM=VB,LRECL=6140,BLKSIZE=0)
//SYSPRINT DD SYSOUT=*
//SYSTSIN DD *
OCOPY INDD(HFSOUT) OUTDD(STDOUTL)
OCOPY INDD(HFSERR) OUTDD(STDERRL)
/*
//
Figure 53. BPXBATCH JCL
Executing PGM=BPXBATCH with PARM=’SH /u/imsres4/Dealerscript.ver3’
indicates that we want to execute a shell script. In our case we executed the
Dealerscript.ver3 script (see Figure 54) from the /u/imsres4 directory. (Notice
that this script actually executes two other scripts.) When the shell starts up,
you are in the HOME directory for the user that submitted the job. If you want
to make sure that you execute the correct script no matter who submits the
job, use absolute path names.
Chapter 6. IMSAuto application build and execute 85

# ###############################################################
# CREATED:
# ITSO 8/10/00 - SCRIPT SHELL TO COMPILE AND BIND JAVA CODE
# FOR THE ITSO AUTO DEALER APPLICATION
# resides on /u/imsres4/
# ###############################################################
echo START Dealerscript.ver3 TO COMPILE AND BIND AUTO DEALER APPL
date
cd
cd u/imsres4
. profile.imsjava
. profile.imsres4
cd
cd usr/lpp/hpj/bin
. profile.hpj
cd
cd u/imsres4
Dealerjavac.sh.ver3
Dealerhpj.sh.ver3
Date
echo END Dealerscript.ver3 TO COMPILE AND BIND AUTO/DEALER APPL
Figure 54. Auto Dealer shell script
All the std files you use must be on HFS. stdenv file allows you to define an
environment variable such as HOME or PATH if you want to run a program. It
does not work with shell scripts. The stdin file is an alternative way of getting
input to the shell. If you do not want to use PARM on the EXEC statement,
define stdin like this:
//STDIN DD PATHOPTS=(ORDONLY),PATH=’/u/imsres4/Dealerscript.ver3’
If you run BPXBATCH, you do not see much in the job sysout. The return
code (RC) is 00 if the shell could execute the script or 12 if there was a
serious error. All other output is hidden on HFS within the files defined as
stdout and stderr.
Because it is our objective in this section to do as much as possible in MVS,
we added a step to our BPXBATCH job which will copy the output from the
HFS files to the job sysout.
6.7 OBROWSE and OEDIT: browsing and editing an HFS file
OBROWSE and OEDIT are straightforward. You can call OBROWSE and
OEDIT with or without a path name. If you do not give a path name, an Entry
Panel is displayed, where you can enter the directory name and file name of a
file you want to browse or edit.
86 IMS Version 7 and Java Application Programming

6.8 OCOPY: Copying to another member or file
You can use the OCOPY command to copy data between an MVS data set
and the HFS, between two data sets, or between two files. For OCOPY, you
would want to use the CONVERT option for these two situations:
Conversion between code pages IBM-037 and IBM-1047
Conversion between ASCII and code page IBM-1047
The UNIX System Services shell uses code page 1047, and MVS uses a
country extended code page. You can convert data to or from code page
1047 while it is being copied. If you are copying a file with doublebyte data,
do not use the CONVERT option. Before using the OCOPY command, you
must allocate the data set with which you are working. When using the TSO/E
ALLOCATE command or a JCL DD statement to allocate a file or data set,
you can specify the PATHMODE and PATHOPTS parameters along with the
PATH parameter. For information about the use of these parameters with the
JCL statement, see the OS/390 MVS JCL Reference. For information about
the TSO/E ALLOCATE command, see the TSO/E Command Reference.
You can use OCOPY to copy:
1. A member of an MVS PDS or PDSE to a file
2. An MVS sequential data set to a file
3. A file to a member of an MVS PDS or PDSE
4. A file to an MVS sequential data set
5. A file to a file
6. A member of an MVS PDS or PDSE to another member of an MVS PDS or
PDSE
7. A member of an MVS PDS or PDSE to an MVS sequential data set
8. An MVS sequential data set to another MVS sequential data set
9. An MVS sequential data set to a member of an MVS PDS or PDSE
Both the source and the target can be an MVS data set, a member of a PDS,
or an HFS file. If the source (INDD) is an MVS data set and the target
(OUTDD) is an HFS file, OCOPY copies an MVS data set to a file; the
operation is the same as the OPUT command. If the source (INDD) is an HFS
file and the target (OUTDD) is an MVS data set, then OCOPY copies a file to
an MVS data set; the operation is the same as the OGET command.
Chapter 6. IMSAuto application build and execute 87

If PATHMODE, which sets the permission bits for a new file, is specified
during allocation, it is used when creating a new file. If PATHMODE is not
specified during the allocation of a new file, the allocation creates a file with
the default permission of 000, which means the user has no access to it. We
used OCOPY to put the output of a job written into HFS files into the job
sysout stream.
6.9 OGET, OGETX, OPUT, and OPUTX: Copying files and members
OGET and OGETX copy files from HFS directory to an MVS PDS, or PDSE,
or a sequential file.
OPUT and OPUTX copy members from an MVS PDS or PDSE to an HFS
directory. The only difference between these commands and OCOPY is that
you do not have to specify the file names within the JCL, rather you specify
the file name within the command. Therefore these commands are more
suited for use as TSO/E commands than for use in a job, as you do not have
to ALLOCATE the files. Here is an example of copying from HFS to an MVS
PDS member:
OGET ‘/u/imsres4/auto.trace’ PDS.DEALERSHIP(TRACE) CONVERT(YES)
For more details on OGET, OGETX, OPUT, OPUTX, and OCOPY, see the
OS/390 UNIX System Services User’s Guide, SC28-1891 and OS/390 UNIX
System Services Command Reference, SC28-1892.
6.10 Java Tools in UNIX System Services environment
In this section we explain how to use the javac and hpj commands in a UNIX
System Services environment. Both tools can be run interactively from the
OMVS command shell or in the background via a BPXBATCH shell script job.
6.10.1 javac command
The javac command compiles Java source code into Java bytecodes. The
java command is used to interpret and run the Java bytecodes.
Java source code must be in files whose names end with the .java extension.
The file name must be constructed from the class name (classname.java) if
the class is public or is referenced from another source file.
88 IMS Version 7 and Java Application Programming

For each class defined in a source file compiled by javac, the compiler stores
the resulting bytecodes in a class file with a name of the form
classname.class. The compiler places each class file in the same directory as
the corresponding source file, unless you specify the -d option.
When the compiler must refer to your own classes you need to specify their
location. Use the -classpath option or CLASSPATH environment variable to
do this. The class path is a sequence of directories (or zip files) which javac
searches for classes not already defined in any of the files specified directly
as command arguments. The compiler looks in the class path for both a
source file and a class file, recompiling the source (and regenerating the
class file) if it is newer.
Set the property javac.pipe.output to true to send output messages to
System.out. Set javac.pipe.output to false, to send output messages to
System.err. Refer to the OS/390 UNIX documentation for more details on the
use of the javac command.
Here are some of the options for the javac command:
-classpath path
Specifies the path javac uses to look up classes needed to run javac or
being referenced by other classes you are compiling. It overrides the
default or the CLASSPATH environment variable if it is set. Use this option
when you want to compile without modifying the CLASSPATH
environment variable. Directories are separated by semi-colons. It is often
useful for the directory containing the source files to be on the class path.
You should always include the system classes at the end of the path. For
example:
javac -classpath .;C:\usr\lpp\ims\imsjava71\classes ...
-d directory
Specifies the root directory of the class file hierarchy where compiled
classes are stored. In other words, this is essentially a destination
directory for your compiled classes. This parameter is useful because
classes are often organized in a hierarchical directory structure.
With this parameter, the directories are created below the directory
specified by . For example, the following command causes the class
files for the classes in the IMSAuto.java source file to be saved in the
directory C:\u\imsres4\dealership\application\classes:
javac -d C:\u\imsres4\dealership\application\classes IMSAuto.java
Chapter 6. IMSAuto application build and execute 89

Note
Note that the -classpath and -d options have independent effects. The
compiler reads only from the class path, and writes only to the destination
directory. It is often useful for the destination directory to be on the class
path. If the -d option is not specified, the source files should be stored in a
directory hierarchy which reflects the package structure, so that the
resulting class files can be easily located.
-encoding encoding name
Specify the source file encoding name, such as EUCJIS\SJIS. If this
option is not specified, then the platform default converter is used.
-deprecation
Generate a warning for every use or override of a deprecated member or
class. A member or class is deprecated if its documentation comment
contains the @deprecated tag. The compiler will emit a warning at the end
of compilation whether or not -deprecation is used; this option causes the
location of each individual use or override to be noted.
Deprecated members or classes are deliberately not mentioned if the
source file containing the deprecation is being recompiled. This can
happen because the file is on the command line or because -depend is
used and the source file was out of date.
-nowarn
Turns off warnings. If used, the compiler does not print out any warnings.
-g
Compiles your code with debug information. Enables generation of
information about local variables for use by Java debugging tools. Use this
option if you want to examine the contents of local variables when
debugging your classes. You can still set breakpoints. Step through your
code if you do not compile your classes with this option. By default, only
line number information is generated.
With JDK 1.1.8, the -g and -O options are mutually exclusive.
-g:nodebug
Do not generate line number or local variable debugging information.
90 IMS Version 7 and Java Application Programming

-O
Directs the compiler to try to generate faster code. This may slow down
compilation, make larger class files, and/or make it difficult to debug.
With JDK 1.1.8, the -O option tries to inline methods across classes. This
creates compatibility problems and sometimes generates illegal bytecode.
-O also implicitly turns on -depend and implicitly turns off -g.
-O:interclass
This option optimizes your code by informing the compiler that all
generated class files are guaranteed to be delivered and upgraded as a
unit, enabling interclass optimizations that may otherwise break binary
compatibility. Use this option with discretion.
There are situations in which it is legal to use a Java compiler to inline
methods. The compiler will only optimize code for which source is
available during the compilation, so the only .java files discoverable by the
compiler should be for classes intended to be delivered or upgraded as a
unit. In particular, ensure that no sources for other classes are accessible
on CLASSPATH, keeping in mind that the present working directory, ‘.’, is
appended to CLASSPATH.
Line number debugging information in class files compiled with
-O:interclass may refer to lines of a different source file. This is a limitation
of the class file format, which does not allow the originating file to be
encoded along with the line number.
This option implicitly turns on -depend.
-verbose
Causes the compiler and linker to print out messages about what source
files are being compiled and what class files are being loaded.
-depend
Causes recompilation of class files on which the source files given as
command line arguments recursively depend. Without this option, only
files that are directly depended on and missing or out-of-date will be
recompiled. Recompilation does not extend to missing or out-of-date files
only depended on by already up-to-date class files.
Chapter 6. IMSAuto application build and execute 91

-Jjavaoption
Passes through the string javaoption as a single argument to the Java
interpreter which runs the compiler. The argument should not contain
spaces. Multiple argument words must all begin with the prefix -J, which is
stripped. This is useful for adjusting the compiler’s execution environment
or memory usage.
Refer to the OS/390 UNIX documentation for more details on the use of the
javac command.
In our testing we executed javac in the foreground and the backgound and
compiled a single class and multiple classes at one time. Here are the
foreground commands we used to compile the Classes for the Auto
Dealership application.
First, we execute the necessary profile commands; second, we change to the
directory holding the class(es) we want to compile; third, we run javac,
supplying one or more class names and options.:
. profile.imsjava
. Profile.imsres4
cd /u/imsres4/dealership/database
javac *.java -verbose
92 IMS Version 7 and Java Application Programming
cd /u/imsres4/dealership/application
javac *.java -verbose
javac IMSAuto.java -verbose
Figure 55 and Figure 56 list the profiles we used to initialize the variables
needed during the compile.
export IBMIMSJ_HOME=/usr/lpp/ims/imsjava71/classes.zip
export CLASSPATH=$CLASSPATH:$IBMIMSJ_HOME
#
# COMMENT HOLDER
#
echo ‘*------------------------------------------------------*
echo ‘ profile.imsjava executed ‘
echo ‘*------------------------------------------------------*
Figure 55. The profile, profile.imsjava

# ====================================================
#JDK
# ====================================================
export JAVA_HOME=/usr/lpp/java18i/J1.1
export PATH=/usr/lpp/java18i/J1.1/bin:$PATH
export CLASSPATH=/usr/lpp/java18i/J1.1/lib/classes.zip:$CLASSPATH
export LD_LIBRARY_PATH=/usr/lpp/java18i/J1.1/lib/classes.zip:$LD_LIBRARY_PATH
# ===================================================================
#HPJ
# ===================================================================
export IMSRES4_HOME=”/u/imsres4”
export IBMHPJ_HOME=”/usr/lpp/hpj”
export IBMHPJ_RTL=”CEE.SCEELKED:CEE.SCEELKEX:CEE.SCEEOBJ:CEE.SCEECPP”
export CLASSPATH=$CLASSPATH:$IBMHPJ_HOME/lib
export CLASSPATH=$CLASSPATH:$IMSRES4_HOME
export PATH=$PATH:$IBMHPJ_HOME/bin
export LIBPATH=$LIBPATH:$IBMHPJ_HOME/lib
export STEPLIB=$STEPLIB:HPJ390.SHPJMOD:HPJ390.SHPOMOD:CEE.SCEERUN
# ===================================================================
echo ********************************
echo ***** profile.imsres4 **********
echo ***** profile.imsres4 **********
echo JAVA_HOME : $JAVA_HOME
echo
echo PATH : $PATH
echo
echo LIBPATH : $LIBPATH
echo
echo CLASSPATH : $CLASSPATH
echo
echo LD_LIBRARY_PATH : $LD_LIBRARY_PATH
echo
echo STEPLIB : $STEPLIB
echo
echo IBMHPJ_HOME : $IBMHPJ_HOME
echo
echo IBMHPJ_RTL : $IBMHPJ_RTL
echo ***** profile.imsres4 **********
echo ***** profile.imsres4 **********
echo ********************************
Figure 56. The profile, profile.imsres4
Figure 57, Figure 58, and Figure 59 contain sample javac output when
executed from an interactive OMVS session.
Chapter 6. IMSAuto application build and execute 93

IMSRES4 @ SC47:/u/imsres4/dealership/database>javac *.java -verbose
parsed Dealer.java in 370 ms¨
parsed Model.java in 36 ms¨
parsed Order.java in 30 ms¨
parsed Sales.java in 21 ms¨
parsed Salesperson.java in 13 ms¨
parsed Stock.java in 32 ms¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/db/DLISegment.class) in 46 ms¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIBaseSegment.class) in 124 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Object.class) in 11 ms¨
checking class dealership.database.Dealer¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Cloneable.class) in 4 ms¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfo.class) in 21 ms¨
wrote Dealer.class¨
checking class dealership.database.Model¨
wrote Model.class¨
checking class dealership.database.Order¨
wrote Order.class¨
checking class dealership.database.Sales¨
wrote Sales.class¨
checking class dealership.database.Salesperson¨
wrote Salesperson.class¨
checking class dealership.database.Stock¨
wrote Stock.class¨
done in 2779 ms¨
IMSRES4 @ SC47:/u/imsres4/dealership/database>
Figure 57. First sample of javac output
94 IMS Version 7 and Java Application Programming

IMSRES4 @ SC47:/u/imsres4/dealership/application>javac *.java -verbose
parsed AcceptOrderInput.java in 234 ms¨
parsed CancelOrderInput.java in 26 ms¨
parsed Cancelled.java in 21 ms¨
parsed CarFound.java in 63 ms¨
parsed DealerDatabaseView.java in 28 ms¨
parsed ErrorMessage.java in 14 ms¨
parsed FindACarInput.java in 29 ms¨
parsed IMSAuto.java in 484 ms¨
parsed InputMessage.java in 31 ms¨
parsed ListModelsInput.java in 43 ms¨
parsed ModelDetails.java in 35 ms¨
parsed ModelList.java in 20 ms¨
parsed OrderAccepted.java in 10 ms¨
parsed OutputMessage.java in 41 ms¨
parsed RecordASaleInput.java in 66 ms¨
parsed SalesRecord.java in 36 ms¨
parsed ShowModelDetailsInput.java in 31 ms¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSFieldMessage.class) in 49 ms¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIBaseSegment.class) in 121 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Object.class) in 11 ms¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/db/DLIDatabaseView.class) in 16 ms¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSApplication.class) in 18 ms¨
checking class dealership.application.AcceptOrderInput¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Cloneable.class) in 3 ms¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfo.class) in 19 ms¨
wrote AcceptOrderInput.class¨
checking class dealership.application.CancelOrderInput¨
wrote CancelOrderInput.class¨
checking class dealership.application.Cancelled¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/IllegalArgumentException.class) in 5 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/RuntimeException.class) in 4 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Exception.class) in 6 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Throwable.class) in 11 ms¨
wrote Cancelled.class¨
checking class dealership.application.CarFound¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfoList.class) in 3 ms¨
wrote CarFound.class¨
checking class dealership.application.DealerDatabaseView¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/db/DLISegmentInfo.class) in 5 ms¨
loaded /u/imsres4/dealership/database/Dealer.class in 10 ms¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/db/DLISegment.class) in 1 9 ms¨
loaded /u/imsres4/dealership/database/Model.class in 5 ms¨
loaded /u/imsres4/dealership/database/Order.class in 13 ms¨
loaded /u/imsres4/dealership/database/Sales.class in 25 ms¨
loaded /u/imsres4/dealership/database/Stock.class in 14 ms¨
wrote DealerDatabaseView.class¨
checking class dealership.application.ErrorMessage¨
wrote ErrorMessage.class¨
checking class dealership.application.FindACarInput¨
wrote FindACarInput.class¨
Figure 58. Another sample of javac output (part 1 of 2)
Chapter 6. IMSAuto application build and execute 95

checking class dealership.application.IMSAuto¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/IMSException.class) in 13 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/io/FileWriter.class) in 7 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/io/OutputStreamWriter.class) in 16 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/io/Writer.class) in 6 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/String.class) in 35 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/io/FileDescriptor.class) in 7 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/io/Serializable.class) in 3 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/io/File.class) in 28 ms¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/IMSTrace.class) in 34 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/System.class) in 25 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Error.class) in 4 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/io/IOException.class) in 4 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/sql/Connection.class) in 12 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/io/PrintStream.class) in 16 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/io/FilterOutputStream.class) in 6 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/io/OutputStream.class) in 4 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/sql/Statement.class) in 8 ms¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSTransaction.class) in 19 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/sql/SQLException.class) in 14 ms¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIException.class) in 6 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/StringBuffer.class) in 22 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Integer.class) in 19 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Number.class) in 5 ms¨
Loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSMessageQueue.class) in 23 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Class.class) in 32 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/sql/DriverManager.class) in 26 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/ExceptionInInitializerError.class) in 5 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/LinkageError.class) in 4 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/ClassNotFoundException.class) in 4 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/sql/ResultSet.class) in 18 ms¨
wrote IMSAuto.class¨
checking class dealership.application.InputMessage¨
wrote InputMessage.class¨
checking class dealership.application.ListModelsInput¨
wrote ListModelsInput.class¨
checking class dealership.application.ModelDetails¨
wrote ModelDetails.class¨
checking class dealership.application.ModelList¨
wrote ModelList.class¨
checking class dealership.application.OrderAccepted¨
wrote OrderAccepted.class¨
checking class dealership.application.OutputMessage¨
wrote OutputMessage.class¨
checking class dealership.application.RecordASaleInput¨
wrote RecordASaleInput.class¨
checking class dealership.application.SalesRecord¨
wrote SalesRecord.class¨
checking class dealership.application.ShowModelDetailsInput¨
wrote ShowModelDetailsInput.class¨
done in 6813 ms¨
IMSRES4 @ SC47:/u/imsres4/dealership/application>
Figure 59. Another sample of javac output (part 2 of 2)
96 IMS Version 7 and Java Application Programming

Here is the the BPXBATCH JCL (Figure 60) and the shell script (Figure 61),
which we used to compile all the Classes for the Auto Dealership application
individually, as well as the STDERRL DD from the BPXBATCH job sysout
(Figure 62 through Figure 67).
//AUTOJAVA JOB (999,POK),’ITSO IMS TEAM’,MSGCLASS=U,CLASS=A,
// NOTIFY=&SYSUID,TIME=1440,REGION=0M
//* ------------------------------------------------------------------
//* EXECUTE SCRIPT
//* ------------------------------------------------------------------
//UXCALL EXEC PGM=BPXBATCH,REGION=0M,
// PARM=’SH /u/imsres4/Dealerjavac.sh.ver3’
//STEPLIB DD DISP=SHR,DSN=CEE.SCEERUN
//STDENV DD DUMMY
//STDIN DD DUMMY
//************************************* THE OUTPUT *********
//STDOUT DD PATH=’/u/imsres4/&SYSUID..autohpj.d080800.eout’,
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),PATHMODE=SIRWXU
//************************************* THE ERRORS *********
//STDERR DD PATH=’/u/imsres4/&SYSUID..autohpj.d080800.eerr’,
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),PATHMODE=SIRWXU
//************************************* THE SYSOUT *********
//SYSPRINT DD SYSOUT=*
//* ------------------------------------------------------------------
//* COPY RESULT(HFS) TO SYSOUT
//* ------------------------------------------------------------------
//HFS2PRT EXEC PGM=IKJEFT01,DYNAMNBR=300,COND=EVEN
//SYSTSPRT DD SYSOUT=*
//HFSOUT DD PATH=’/u/imsres4/&SYSUID..autohpj.d080800.eout’
//HFSERR DD PATH=’/u/imsres4/&SYSUID..autohpj.d080800.eerr’
//STDOUTL DD SYSOUT=*,DCB=(RECFM=VB,LRECL=6140,BLKSIZE=0)
//STDERRL DD SYSOUT=*,DCB=(RECFM=VB,LRECL=6140,BLKSIZE=0)
//SYSPRINT DD SYSOUT=*
//SYSTSIN DD *
OCOPY INDD(HFSOUT) OUTDD(STDOUTL)
OCOPY INDD(HFSERR) OUTDD(STDERRL)
/*
//
Figure 60. BPXBATCH JCL that executes shell script
Chapter 6. IMSAuto application build and execute 97

# ###############################################################
# CREATED:
# ITSO 08/10/00 - javac compile of ITSO AUTO DEALER APPL
# ###############################################################
echo BEGIN Dealerjavac.sh.ver3
cd
cd /u/imsres4
javac dealership/database/*.java -verbose
javac dealership/application/AcceptOrderInput.java -verbose
javac dealership/application/Cancelled.java -verbose
javac dealership/application/CancelOrderInput.java -verbose
javac dealership/application/CarFound.java -verbose
javac dealership/application/DealerDatabaseView.java -verbose
javac dealership/application/ErrorMessage.java -verbose
javac dealership/application/FindACarInput.java -verbose
javac dealership/application/InputMessage.java -verbose
javac dealership/application/ListModelsInput.java -verbose
javac dealership/application/ModelDetails.java -verbose
javac dealership/application/ModelList.java -verbose
javac dealership/application/OrderAccepted.java -verbose
javac dealership/application/OutputMessage.java -verbose
javac dealership/application/RecordASaleInput.java -verbose
javac dealership/application/SalesRecord.java -verbose
javac dealership/application/ShowModelDetailsInput.java -verbose
javac dealership/application/IMSAuto.java -verbose
echo END Dealerjavac.sh.ver3
# ##########################################################
# #### FOLLOWING javac COMPILE ORDER WILL NOT WORK
# #### database/*.java MUST BE COMPILED FIRST
# #### application/*.java MUST BE COMPILED SECOND
# #### IMSAuto.java HAS TO BE COMPILED LAST TO WORK
# ##########################################################
# javac dealership/database/*.java -verbose
# javac dealership/application/*.java -verbose
Figure 61. Shell script to compile the auto dealer program
98 IMS Version 7 and Java Application Programming

java version “1.1.8”
hpjava version “VisualAge 2.0 CL4.1 - May 26 2000”
parsed dealership/database/Dealer.java in 221 ms
parsed dealership/database/Model.java in 18 ms
parsed dealership/database/Order.java in 18 ms
parsed dealership/database/Sales.java in 15 ms
parsed dealership/database/Salesperson.java in 12 ms
parsed dealership/database/Stock.java in 14 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/db/DLISegment.class) in 43 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIBaseSegment.class) in 121 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Object.class) in 11 ms
checking class dealership.database.Dealer
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Cloneable.class) in 3 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfo.class) in 21 ms
wrote dealership/database/Dealer.class
checking class dealership.database.Model
wrote dealership/database/Model.class
checking class dealership.database.Order
wrote dealership/database/Order.class
checking class dealership.database.Sales
wrote dealership/database/Sales.class
checking class dealership.database.Salesperson
wrote dealership/database/Salesperson.class
checking class dealership.database.Stock
wrote dealership/database/Stock.class
done in 2952 ms
parsed dealership/application/AcceptOrderInput.java in 216 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSFieldMessage.class) in 48 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIBaseSegment.class) in 129 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Object.class) in 11 ms
checking class dealership.application.AcceptOrderInput
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Cloneable.class) in 4 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfo.class) in 19 ms
loaded ./dealership/application/InputMessage.class in 14 ms
wrote dealership/application/AcceptOrderInput.class
done in 2041 ms
parsed dealership/application/Cancelled.java in 224 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSFieldMessage.class) in 46 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIBaseSegment.class) in 139 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Object.class) in 11 ms
checking class dealership.application.Cancelled
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Cloneable.class) in 3 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfo.class) in 58 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/IllegalArgumentException.class) in 4 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/RuntimeException.class) in 3 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Exception.class) in 5 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Throwable.class) in 11 ms
wrote dealership/application/Cancelled.class
done in 2178 ms
parsed dealership/application/CancelOrderInput.java in 231 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSFieldMessage.class) in 47 ms
Figure 62. STDERRL DD SYSOUT from BPXBATCH job (part 1 of 6)
Chapter 6. IMSAuto application build and execute 99

loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIBaseSegment.class) in 123 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Object.class) in 11 ms
checking class dealership.application.CancelOrderInput
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Cloneable.class) in 37 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfo.class) in 23 ms
loaded ./dealership/application/InputMessage.class in 3 ms
wrote dealership/application/CancelOrderInput.class
done in 2024 ms
parsed dealership/application/CarFound.java in 227 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSFieldMessage.class) in 52 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIBaseSegment.class) in 133 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Object.class) in 11 ms
checking class dealership.application.CarFound
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Cloneable.class) in 4 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfo.class) in 21 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfoList.class) in 4 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/IllegalArgumentException.class) in 4 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/RuntimeException.class) in 3 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Exception.class) in 5 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Throwable.class) in 10 ms
wrote dealership/application/CarFound.class
done in 2076 ms
parsed dealership/application/DealerDatabaseView.java in 223 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/db/DLIDatabaseView.class) in 42 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Object.class) in 11 ms
checking class dealership.application.DealerDatabaseView
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/db/DLISegmentInfo.class) in 5 ms
loaded ./dealership/database/Dealer.class in 5 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/db/DLISegment.class) in 19 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIBaseSegment.class) in 161 ms
loaded ./dealership/database/Model.class in 4 ms
loaded ./dealership/database/Order.class in 4 ms
loaded ./dealership/database/Sales.class in 4 ms
loaded ./dealership/database/Stock.class in 5 ms
wrote dealership/application/DealerDatabaseView.class
done in 2081 ms
parsed dealership/application/ErrorMessage.java in 216 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSFieldMessage.class) in 47 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIBaseSegment.class) in 176 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Object.class) in 11 ms
checking class dealership.application.ErrorMessage
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Cloneable.class) in 4 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfo.class) in 21 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/IllegalArgumentException.class) in 4 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/RuntimeException.class) in 5 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Exception.class) in 5 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Throwable.class) in 11 ms
wrote dealership/application/ErrorMessage.class
done in 2028 ms
parsed dealership/application/FindACarInput.java in 228 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSFieldMessage.class) in 48 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIBaseSegment.class) in 155 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Object.class) in 10 ms
checking class dealership.application.FindACarInput
Figure 63. STDERRL DD SYSOUT from BPXBATCH job (part 2 of 6)
100 IMS Version 7 and Java Application Programming

checking class dealership.application.FindACarInput
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Cloneable.class) in 3 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfo.class) in 20 ms
loaded ./dealership/application/InputMessage.class in 4 ms
wrote dealership/application/FindACarInput.class
done in 2022 ms
parsed dealership/application/InputMessage.java in 221 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSFieldMessage.class) in 47 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIBaseSegment.class) in 161 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Object.class) in 10 ms
checking class dealership.application.InputMessage
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Cloneable.class) in 3 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfo.class) in 20 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/IllegalArgumentException.class) in 3 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/RuntimeException.class) in 4 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Exception.class) in 5 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Throwable.class) in 10 ms
wrote dealership/application/InputMessage.class]
done in 2029 ms
parsed dealership/application/ListModelsInput.java in 217 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSFieldMessage.class) in 47 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIBaseSegment.class) in 195 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Object.class) in 11 ms
checking class dealership.application.ListModelsInput
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Cloneable.class) in 3 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfo.class) in 20 ms
loaded ./dealership/application/InputMessage.class in 4 ms
wrote dealership/application/ListModelsInput.class
done in 2072 ms
parsed dealership/application/ModelDetails.java in 224 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSFieldMessage.class) in 47 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIBaseSegment.class) in 172 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Object.class) in 11 ms
checking class dealership.application.ModelDetails
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Cloneable.class) in 5 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfo.class) in 20 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/IllegalArgumentException.class) in 4 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/RuntimeException.class) in 3 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Exception.class) in 5 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Throwable.class) in 10 ms
wrote dealership/application/ModelDetails.class
done in 2059 ms
parsed dealership/application/ModelList.java in 293 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSFieldMessage.class) in 72 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIBaseSegment.class) in 151 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Object.class) in 13 ms
checking class dealership.application.ModelList
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Cloneable.class) in 4 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfo.class) in 27 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfoList.class) in 7 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/IllegalArgumentException.class) in 5 ms
Figure 64. STDERRL DD SYSOUT from BPXBATCH job (part 3 of 6)
Chapter 6. IMSAuto application build and execute 101

loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/RuntimeException.class) in 7 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Exception.class) in 6 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Throwable.class) in 14 ms
wrote dealership/application/ModelList.class
done in 3120 ms
parsed dealership/application/OrderAccepted.java in 214 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSFieldMessage.class) in 86 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIBaseSegment.class) in 125 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Object.class) in 12 ms
checking class dealership.application.OrderAccepted
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Cloneable.class) in 4 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfo.class) in 20 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/IllegalArgumentException.class) in 4 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/RuntimeException.class) in 4 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Exception.class) in 5 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Throwable.class) in 9 ms
wrote dealership/application/OrderAccepted.class
done in 2027 ms
parsed dealership/application/OutputMessage.java in 239 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSFieldMessage.class) in 100 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIBaseSegment.class) in 130 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Object.class) in 11 ms
checking class dealership.application.OutputMessage
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Cloneable.class) in 3 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfo.class) in 20 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/IllegalArgumentException.class) in 4 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/RuntimeException.class) in 4 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Exception.class) in 4 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Throwable.class) in 10 ms
wrote dealership/application/OutputMessage.class
done in 2135 ms
parsed dealership/application/RecordASaleInput.java in 232 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSFieldMessage.class) in 50 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIBaseSegment.class) in 124 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Object.class) in 13 ms
checking class dealership.application.RecordASaleInput
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Cloneable.class) in 3 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfo.class) in 20 ms
loaded ./dealership/application/InputMessage.class in 4 ms
wrote dealership/application/RecordASaleInput.class
done in 2096 ms
parsed dealership/application/SalesRecord.java in 216 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSFieldMessage.class) in 47 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIBaseSegment.class) in 125 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Object.class) in 11 ms
checking class dealership.application.SalesRecord
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Cloneable.class) in 4 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfo.class) in 20 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/IllegalArgumentException.class) in 4 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/RuntimeException.class) in 4 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Exception.class) in 5 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Throwable.class) in 11 ms
Figure 65. STDERRL DD SYSOUT from BPXBATCH job (part 4 of 6)
102 IMS Version 7 and Java Application Programming

wrote dealership/application/SalesRecord.class
done in 2104 ms
parsed dealership/application/ShowModelDetailsInput.java in 229 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSFieldMessage.class) in 48 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIBaseSegment.class) in 125 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Object.class) in 11 ms
checking class dealership.application.ShowModelDetailsInput
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Cloneable.class) in 3 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfo.class) in 22 ms
loaded ./dealership/application/InputMessage.class in 4 ms
wrote dealership/application/ShowModelDetailsInput.class
done in 2021 ms
parsed dealership/application/IMSAuto.java in 696 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSApplication.class) in 45 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Object.class) in 11 ms
checking class dealership.application.IMSAuto
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/IMSException.class) in 11 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/io/FileWriter.class) in 7 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/io/OutputStreamWriter.class) in 20 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/io/Writer.class) in 6 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/String.class) in 73 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/io/FileDescriptor.class) in 7 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/io/Serializable.class) in 3 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/io/File.class) in 25 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/IMSTrace.class) in 32 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Exception.class) in 5 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/System.class) in 25 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Throwable.class) in 9 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Error.class) in 3 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/RuntimeException.class) in 3 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/io/IOException.class) in 4 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/sql/Connection.class) in 12 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSFieldMessage.class) in 20 ms
loaded ./dealership/application/AcceptOrderInput.class in 4 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/io/PrintStream.class) in 17 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/io/FilterOutputStream.class) in 6 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/io/OutputStream.class) in 5 ms
loaded ./dealership/application/OrderAccepted.class in 4 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIBaseSegment.class) in 123 ms]
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfo.class) in 20 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/sql/Statement.class) in 9 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSTransaction.class) in 19 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/sql/SQLException.class) in 11 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIException.class) in 6 ms
loaded ./dealership/application/CancelOrderInput.class in 5 ms
loaded ./dealership/application/Cancelled.class in 3 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/StringBuffer.class) in 23 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Integer.class) in 20 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Number.class) in 6 ms
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSMessageQueue.class) in 27 ms
loaded ./dealership/application/InputMessage.class in 3 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Class.class) in 32 ms
Figure 66. STDERRL DD SYSOUT from BPXBATCH job (part 5 of 6)
Chapter 6. IMSAuto application build and execute 103

loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/sql/DriverManager.class) in 25 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/ExceptionInInitializerError.class) in 5 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/LinkageError.class) in 4 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/ClassNotFoundException.class) in 4 ms
loaded ./dealership/application/FindACarInput.class in 5 ms
loaded ./dealership/application/ShowModelDetailsInput.class in 4 ms
loaded ./dealership/application/RecordASaleInput.class in 4 ms
loaded ./dealership/application/CarFound.class in 5 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/sql/ResultSet.class) in 16 ms
loaded ./dealership/application/ModelList.class in 5 ms
loaded ./dealership/application/SalesRecord.class in 3 ms
loaded ./dealership/application/ErrorMessage.class in 4 ms
loaded ./dealership/application/ModelDetails.class in 4 ms
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Cloneable.class) in 3 ms
wrote dealership/application/IMSAuto.class
done in 4598 ms
Figure 67. STDERRL DD SYSOUT from BPXBATCH job (part 6 of 6)
6.10.2 The hpj command
The Enterprise ToolKit for OS/390 provides a High Performance Java
compiler which enables you to build platform-specific Java executables and
DLLs. You can use the hpj command to bind Java bytecode files into a Java
executable or DLL that runs in the OS/390 UNIX or IMS/ESA environment.
The hpj command has the following syntax:
hpj {[options] inputfiles [options]}...
All command options begin with a dash (-) and can be entered sequentially.
With the exception of the -B option, they must be separated from associated
arguments by a space. The options can appear before, after, or between
input file names. All of the options apply to all input files. If the same option
appears more than once, the last occurrence of the option is used. Appendix
J, “Options for the hpj command” on page 385 lists the valid options for the
hpj command:
For a complete list of the hpj command options, refer to ET/390
documentation.
Note
A new parameter, -target=IMS | -target=LE, must be specified to build an
IMS Java executable or DLL.
Figure 68 illustrates the hpj command we used to create the Auto Dealership
IMSAUTO executable in a PDSE PGMLIB. Note that we specified -target=IMS
104 IMS Version 7 and Java Application Programming

and that the PGMLIB must be a PDSE. The -include was necessary to
resolve the DealerDatabaseView Class, and -exclude was used so that the
IMS Java Library Classes would be dynamically resolved at runtime.
hpj dealership.application.IMSAuto \
-main=dealership.application.IMSAuto \
-o=”//’IMS.SJIMSR.IVP.PGMLIB(IMSAUTO)’” -alias=IMSAUTO \
-target=IMS \
-lerunopts=”ENVAR(CLASSPATH=$IMSJAVA:$IMSJDLL:$IMSCLIB:$IMSHPJ”) \
-verbose \
-include=dealership.application.DealerDatabaseView \
-exclude=com.ibm.ims.db.* \
-exclude=com.ibm.ims.application.* \
-exclude=com.ibm.ims.base.*
Figure 68. Example of hpj command
The following types of files are processed by the hpj command:
6.10.2.1 Input files
All input files must be on HFS except Java executables and Java DLLs. The
executables and DLLs can either be on HFS or in a PDSE.
The hpj command recognizes these types of input files:
Class names (CLASSPATH is used to find the files). For example: hpj
-o=queryEmp Abc.staff.queryDB.queryMain
Partially bound program objects (.o files). For example: hpj -o=queryEmp
abc.staff.queryDB.queryMain.mo abc.staff.queryDB.readDB.o
A Java DLL or a Java executable specified with the -o option. For
example: hpj -o=queryEmp -classpath=/home/ts123456/app.zip \
-include=abc.staff.queryDB.* \ -partial=abc.staff.queryDB.readDB
JAR files (.jar) containing packages or classes. For example: hpj
-o=queryEmp abcstaff.jar
ZIP files (.zip) containing packages or classes. For example: hpj
-o=queryEmp abcstaff.zip
6.10.2.2 Output files
The hpj command generates the following output files:
A Java executable or Java DLL on HFS or in a PDSE member
- A Java executable when the -exe option is specified or when neither -jll
nor -exe is specified
- A Java DLL when the -jll option is specified
Chapter 6. IMSAuto application build and execute 105

Note
Java executables or DLLs running under IMS must reside in PDSE
PGMLIBs. To specify a PDSE data set and member name, you must
use the -o option. For Java DLLs residing in PDSE members, you must
also use the -alias option to give the member an HFS-like DLL name.
Partially bound program objects (.o, .mo, .ro, .po files) on HFS
- The hpj command automatically generates .o files. One .o file is
created for each class. The name of the .o file is the class name. These
.o files must be written to HFS. The -collapse and -d options can be
used to control the placement of .o Files.
- The .mo file is also automatically generated by the hpj command. If -jll
is specified, the .mo file is not generated. When the -main option is
specified, a .mo file is generated (in addition to the .o file) for the
specified main class. If -main is not specified and the -c option is
specified, a .mo file is generated (in addition to the .o file) for the first
class that contains a main method. The name and placement of the
.mo files are the same as those of the .o file for the main class.
- The .ro file is automatically generated by the hpj command when the
-lerunopts option is specified. One .ro file is generated. You can bind
the .ro file only to a Java executable. The name and placement of the
.ro file are the same as those of the .o file for the main class.
- The .po file is automatically generated by the hpj command when the
-resource option is specified. One .po file is generated for all resource
files in the specified ZIP and jar files. You can bind the .po file only to a
Java executable or DLL that is written to a PDSE member. The .po file
is written to the -d directory (if it is specified) or the current directory.
Listing files (.lst files) on HFS. the hpj command generates .lst files
when the -list and/or -inlrpt options are specified. One file is generated for
each class. The name of the .lst file is the class name. These .lst files are
written to the same HFS directories as the corresponding .o files.
A binder map (.map file) on HFS. A map file is always generated unless
both -BNOLIST and -BXREF(NO) are specified. The file is written to the
same location as the Java executable or DLL. However, if the Java
executable or DLL is written to a PDSE member, the .map file is written to
the current directory.
.syslin file. The .syslin file contains the list of program objects that are
bound in Java executable or DLL. It is generated when the -verbose option
106 IMS Version 7 and Java Application Programming

is specified. The file is written to the same location as the Java executable
or DLL. However, if the Java executable or DLL is written to a PDSE
member, the .syslin file is written to the current directory.
Error messages. The error messages are sent to stderr.
6.11 Example of “nonvisual” application development
In this section we explain the steps to follow to modify an IMS Java program
and get it running.
1. Edit the source file on the HFS
We started with a sample IVP application distributed in HFS directory
/usr/lpp/ims/imsjava71/sample/ivp. (See Appendix E to view the source
code for the programs.) We used the ISHELL “C” action code to copy each
of the Java programs to our own HFS directory, /u/imsres4/samples/ivp/.
Then we edited the source code using the ISHELL “E” action code. We
added several System.out.println display instructions and nothing more.
Note
Note that you can import Java code from a workstation to an HFS
directory using FTP. Be aware that the source Java file names are case
sensitive!
2. Compile and link
To quickly compile the Java programs, we executed the javac command
under the OMVS shell (see Figure 69).
Chapter 6. IMSAuto application build and execute 107

IMSRES4 @ SC47:/u/imsres4/samples/ivp>javac *.java -verbose
parsed IVP.java in 483 ms¨
parsed IVPDatabaseView.java in 22 ms¨
parsed InputMessage.java in 63 ms¨
parsed OutputMessage.java in 20 ms¨
parsed PhoneBookSegment.java in 25 ms¨
parsed SPAMessage.java in 29 ms¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSApplication.class) in 46 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Object.class) in 13 ms¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/db/DLIDatabaseView.class) in 16 ms¨ loaded
/usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSFieldMessage.class) in 22 ms¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIBaseSegment.class) in 119 ms¨ loaded
/usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/db/DLISegment.class)in16ms¨ checkingclasssamples.ivp.IVP¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/IMSException.class) in 10 ms¨ loaded
/usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSMessageQueue.class) in 22 ms¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/db/DLIConnection.class) in 25 ms¨ loaded
/usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Exception.class) in 5 ms¨ loaded
/usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/db/SSA.class) in 38 ms¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/db/SSAList.class) in 24 ms¨ loaded
/usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/String.class) in 73 ms¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLITypeInfo.class) in 20 ms¨ loaded
/usr/lpp/java18i/J1.1/lib/classes.zip(java/io/Serializable.class) in 3 ms¨ loaded
/usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Throwable.class) in 10 ms¨ loaded
/usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Error.class) in 4 ms¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/RuntimeException.class) in 6 ms¨ loaded
/usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/DLIException.class) in 5 ms¨ loaded
/usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/Cloneable.class) in 3 ms¨ loaded
/usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/base/JavaToDLI.class) in 124 ms¨ loaded
/usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/application/IMSTransaction.class) in 19 ms¨
loaded/usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/StringBuffer.class)in23ms¨ wroteIVP.class¨
checking class samples.ivp.IVPDatabaseView¨
loaded /usr/lpp/ims/imsjava71/classes.zip(com/ibm/ims/db/DLISegmentInfo.class) in 4 ms¨ wrote
IVPDatabaseView.class¨
checking class samples.ivp.InputMessage¨
loaded /usr/lpp/java18i/J1.1/lib/classes.zip(java/lang/IllegalArgumentException.class) in 4 ms¨
wrote InputMessage.class¨
checking class samples.ivp.OutputMessage¨
wrote OutputMessage.class¨
checking class samples.ivp.PhoneBookSegment¨
wrote PhoneBookSegment.class¨
checking class samples.ivp.SPAMessage¨
wrote SPAMessage.class¨
done in 3733 ms¨
IMSRES4 @ SC47:/u/imsres4/samples/ivp>
Figure 69. javac compile and link
108 IMS Version 7 and Java Application Programming

To bind the programs, we used a BPXBATCH job (see Figure 70) to
execute a shell script (see Figure 71). The shell script does the hpj
compile and bind for the IVP application.
//IVPHPJ JOB (999,POK),’ITSO IMS TEAM’,MSGCLASS=U,CLASS=A,
// NOTIFY=&SYSUID,TIME=1440,REGION=0M
//* ------------------------------------------------------------------
//* EXECUTE SCRIPT
//* ------------------------------------------------------------------
//UXCALL EXEC PGM=BPXBATCH,REGION=0M,
// PARM=’SH /u/imsres4/IVPhpj.sh.ver1’
//STEPLIB DD DISP=SHR,DSN=CEE.SCEERUN
//STDENV DD DUMMY
//STDIN DD DUMMY
//************************************* THE OUTPUT *********
//STDOUT DD PATH=’/u/imsres4/&SYSUID..IVPhpj.a090100.eout’,
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),PATHMODE=SIRWXU
//************************************* THE ERRORS *********
//STDERR DD PATH=’/u/imsres4/&SYSUID..IVPhpj.a090100.eerr’,
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),PATHMODE=SIRWXU
//************************************* THE SYSOUT *********
//SYSPRINT DD SYSOUT=*
//* ------------------------------------------------------------------
//* COPY RESULT(HFS) TO SYSOUT
//* ------------------------------------------------------------------
//HFS2PRT EXEC PGM=IKJEFT01,DYNAMNBR=300,COND=EVEN
//SYSTSPRT DD SYSOUT=*
//HFSOUT DD PATH=’/u/imsres4/&SYSUID..IVPhpj.a090100.eout’
//HFSERR DD PATH=’/u/imsres4/&SYSUID..IVPhpj.a090100.eerr’
//STDOUTL DD SYSOUT=*,DCB=(RECFM=VB,LRECL=6140,BLKSIZE=0)
//STDERRL DD SYSOUT=*,DCB=(RECFM=VB,LRECL=6140,BLKSIZE=0)
//SYSPRINT DD SYSOUT=*
//SYSTSIN DD *
OCOPY INDD(HFSOUT) OUTDD(STDOUTL)
OCOPY INDD(HFSERR) OUTDD(STDERRL)
/*
//
Figure 70. BPXBATCH job
Chapter 6. IMSAuto application build and execute 109

# ##################################################################
# CREATED:
# ITSO 8/20/00 - execute the HPJ binder for the IVP APPL
# ##################################################################
echo BEGIN IVPhpj.sh.ver1
date
cd
cd u/imsres4
. profile.imsjava
. profile.imsres4
cd
cd usr/lpp/hpj/bin
. profile.hpj
#
export IMSJAVA=/usr/lpp/ims/imsjava71
export IMSJDLL=/usr/lpp/ims/imsjava71/imsjava.jll
export IMSCLIB=/usr/lpp/ims/imsjava71/libJavTDLI.dll
export IMSHPJ=/usr/lpp/hpj/lib
export PATH=$PATH:/usr/lpp/hpj/bin
echo IMSJAVA : $IMSJAVA
echo IMSJDLL : $IMSJDLL
echo IMSCLIB : $IMSCLIB
echo IMSHPJ : $IMSHPJ
echo PATH : $PATH
#
cd
cd /u/imsres4/
hpj samples.ivp.IVP \
-main=samples.ivp.IVP \
-o=”//’IMS.SJIMSR.IVP.PGMLIB(DFSIVP32)’” -alias=DFSIVP32 \
-target=IMS \
-lerunopts=”ENVAR(CLASSPATH=$IMSJAVA:$IMSJDLL:$IMSCLIB:$IMSHPJ)” \
-verbose \
-exclude=com.ibm.ims.db.* \
-exclude=com.ibm.ims.application.* \
-exclude=com.ibm.ims.base.*
#
date
echo END IVPhpj.sh.ver1
Figure 71. Shell Script to hpj compile and bind the IVP application
Note that before the hpj command we must position at a directory where
both the Application Class Library and the IMS Java Class Libraries can
be accessed. So, we change the directory to /u/imsres4/. The hpj
command must indicate the specific directories required to access the
input Java main method without the .class extention - samples.ivp.IVP.
The hpj command is continued over many lines with backslashes (‘\’)
used to indicate continuation.
110 IMS Version 7 and Java Application Programming

The following parameters can be used:
- -main indicates the class that contains the main startup. If -main is
omitted, the first class with a main method found is assumed to be the
main startup. This can produce some interesting errors if the program
is changed and your main is no longer the first main. So be sure to
specify -main.
- -alias specifies an alias (HFS-like) name for a Java executable or DLL
that is being written to a PDSE member. -alias must be specified for all
Java DLLs that reside in PDSE members. It is not necessary to specify
-alias for a Java executable, but it does not hurt either.
- -o specifies where to put the executable so IMS can find and access it.
It must be a member of a PDSE, which is included in the Dependent
Region STEPLIB concatenation. Note the double and single quotes
required!
- -target tells hpj to compile and bind Java bytecode files into a Java
executable that runs in the IMS environment.
- -exclude indicates that the classes in the specified Class Libraries are
not to be included in the executable
For more information on the hpj command options available, see
Appendix J, “Options for the hpj command” on page 385.
Figure 72, Figure 73, and Figure 74 show the .profile files that we used.
They set up the Java and hpj paths.
export IBMIMSJ_HOME=/usr/lpp/ims/imsjava71/classes.zip
export CLASSPATH=$CLASSPATH:$IBMIMSJ_HOME
#
# COMMENT HOLDER
#
echo ‘*------------------------------------------------------*
echo ‘ profile.imsjava executed ‘
echo ‘*------------------------------------------------------*
Figure 72. Sample .profile.imsjava file
Chapter 6. IMSAuto application build and execute 111

#====================================================
#JDK
# ====================================================
export JAVA_HOME=/usr/lpp/java18i/J1.1
export PATH=/usr/lpp/java18i/J1.1/bin:$PATH
export CLASSPATH=/usr/lpp/java18i/J1.1/lib/classes.zip:$CLASSPATH
export LD_LIBRARY_PATH=/usr/lpp/java18i/J1.1/lib/classes.zip:$LD_LIBRARY_PATH
# ===================================================================
#HPJ
# ===================================================================
export IMSRES4_HOME=”/u/imsres4”
export IBMHPJ_HOME=”/usr/lpp/hpj”
export IBMHPJ_RTL=”CEE.SCEELKED:CEE.SCEELKEX:CEE.SCEEOBJ:CEE.SCEECPP”
export CLASSPATH=$CLASSPATH:$IBMHPJ_HOME/lib
export CLASSPATH=$CLASSPATH:$IMSRES4_HOME
export PATH=$PATH:$IBMHPJ_HOME/bin
export LIBPATH=$LIBPATH:$IBMHPJ_HOME/lib
export STEPLIB=$STEPLIB:HPJ390.SHPJMOD:HPJ390.SHPOMOD:CEE.SCEERUN
# ===================================================================
#
# ====================================================
echo ********************************
echo ***** profile.imsres4 **********
echo ***** profile.imsres4 **********
echo JAVA_HOME : $JAVA_HOME
echo
echo PATH : $PATH
echo
echo LIBPATH : $LIBPATH
echo
echo CLASSPATH : $CLASSPATH
echo
echo LD_LIBRARY_PATH : $LD_LIBRARY_PATH
echo
echo STEPLIB : $STEPLIB
echo
echo IBMHPJ_HOME : $IBMHPJ_HOME
echo
echo IBMHPJ_RTL : $IBMHPJ_RTL
echo ***** profile.imsres4 **********
echo ***** profile.imsres4 **********
Figure 73. Sample .profile.imsres4 file
112 IMS Version 7 and Java Application Programming

#----------------------------------------------------------------------
# Licensed Materials - Property of IBM.
# 5655-JAV
# (C) Copyright IBM Corp. 1998, 1999
#
# Exports environment variables for VisualAge for Java, Enterprise
# Edition for OS/390
#
# Before using this profile, you have to make the following
# modifications:
#
# 1) Change HPJ and CEE to the appropriate high-level qualifier for
# VisualAge for Java, Enterprise Edition for OS/390 and Language
# Environment.
#
# 2) Change IBMHPJ_HOME to your install directory.
#
#----------------------------------------------------------------------
#
export IBMHPJ_HOME=”/usr/lpp/hpj”
export IBMHPJ_RTL=”CEE.SCEELKED:CEE.SCEELKEX:CEE.SCEEOBJ:CEE.SCEECPP”
export CLASSPATH=$CLASSPATH:.:$IBMHPJ_HOME/lib
export CLASSPATH=$CLASSPATH:$IBMHPJ_HOME/lib/eablib.jar
export CLASSPATH=$CLASSPATH:$IBMHPJ_HOME/lib/recjava.jar
export CLASSPATH=$CLASSPATH:$IBMHPJ_HOME/lib/jdebug.jar
export PATH=$PATH:$IBMHPJ_HOME/bin
export LIBPATH=$LIBPATH:$IBMHPJ_HOME/lib
export STEPLIB=$STEPLIB:HPJ.SHPJMOD:HPJ.SHPOMOD:CEE.SCEERUN
#
echo ‘*---------------------------------------------------------------’
echo ‘ profile.java was executed ‘
echo ‘*---------------------------------------------------------------’
Figure 74. Sample .profile.hpj file
The second step of the BPXBATCH job copied the information about our
batch run to stdout and stderr files. Figure 75 shows the contents of the
STDOUTL file. It contains messages generated when the .profile file was
processed, the names of our input, and output files.
Chapter 6. IMSAuto application build and execute 113

LIBPATH reset to /lib:/usr/lib:/usr/lpp/db2/db2610/lib:
----------------------------------------------------
Set up environment variables for Java for MVS
----------------------------------------------------
Previous environment for Java unset
JAVA_HOME set to /usr/lpp/java18/J1.1
PATH reset to /usr/lpp/java18/J1.1/bin:/usr/lpp/db2/db2610/bin:/bin:.
----------------------------------------------------
CLASSPATH set to .:/usr/lpp/internet/server_root/cgi-bin/icsclass.zip:/usr/lpp/i
LD_LIBRARY_PATH reset to .:/usr/lpp/db2/db2610/bin:/usr/lpp/db2/db2610/lib:/usr/
STEPLIB set to DB2V610J.SDSNEXIT:DSN610.SDSNEXIT:DSN610.SDSNLOAD:HPJ390.SHPJMOD:
DB2SQLJPROPERTIES set to /usr/lpp/db2/db2610/classes/db2sqljjdbc.properties
DB2SQLJDBRMLIB set to DB2V610J.DBRMLIB.DATA
*--------------------------------------------------------------profile
executed for HPJ, JAVA and SQLJ
*---------------------------------------------------------------
BEGIN IVPhpj.sh.ver1
Thu Aug 31 23:43:00 EDT 2000
*------------------------------------------------------*
echo profile.imsjava executed
JAVA_HOME : /usr/lpp/java18i/J1.1
PATH : /usr/lpp/java18i/J1.1/bin:/usr/lpp/java18/J1.1/bin:/usr/lpp/db2/db2610/bi
LIBPATH : /usr/lpp/db2/db2610/lib:/usr/lpp/db2/db2610/lib:/usr/lpp/java18/J1.1/l
CLASSPATH : /usr/lpp/java18i/J1.1/lib/classes.zip:.:/usr/lpp/internet/server_roo
LD_LIBRARY_PATH : /usr/lpp/java18i/J1.1/lib/classes.zip:.:/usr/lpp/db2/db2610/bi
STEPLIB : DB2V610J.SDSNEXIT:DSN610.SDSNEXIT:DSN610.SDSNLOAD:HPJ390.SHPJMOD:HPJ39
IBMHPJ_HOME : /usr/lpp/hpj
IBMHPJ_RTL : CEE.SCEELKED:CEE.SCEELKEX:CEE.SCEEOBJ:CEE.SCEECPP
*--------------------------------------------------------------profile.java
was executed
*---------------------------------------------------------------
IMSJAVA : /usr/lpp/ims/imsjava71
IMSJDLL : /usr/lpp/ims/imsjava71/imsjava.jll
IMSCLIB : /usr/lpp/ims/imsjava71/libJavTDLI.dll
IMSHPJ : /usr/lpp/hpj/lib
PATH : /usr/lpp/java18i/J1.1/bin:/usr/lpp/java18/J1.1/bin:/usr/lpp/db2/db2610/bi
samples.ivp.IVP
samples.ivp.IVPDatabaseView
samples.ivp.InputMessage
samples.ivp.OutputMessage
samples.ivp.PhoneBookSegment
samples.ivp.SPAMessage
//’IMS.SJIMSR.IVP.PGMLIB(DFSIVP32)’
Thu Aug 31 23:43:13 EDT 2000
END IVPhpj.sh.ver1
Figure 75. STDOUTL file
114 IMS Version 7 and Java Application Programming

The STDERRL file (Figure 76) contains the binder messages.
java version “1.1.8”
hpjava version “VisualAge 2.0 CL4.1 - May 26 2000”
IEW2278I B352 INVOCATION PARAMETERS -
TERM,AMODE=31,RENT,DYNAM=DLL,CASE=MIXED,COMPAT=CURR,MSGLEVEL=4
Figure 76. STDERRL File
In the first line you see what file javac was working on. No error messages
were generated. The last part of the output is the output of the binder.
There were no problems here either.
Now we have the following readable files:
- .map file with the binder listing
- .syslin with the input to the binder that was used
We also have the following binary files:
- .class containing the Java byte code
- .mo containing the partly bound main class
(this file is not generated if you use the -jll option)
- .o containing the other partly bound classes
- .ro containing the run-time options
- The executable DFSIVP32 in the PDSE IMS.SJIMSR.IVP.PGMLIB
Sometimes when we invoked hpj from a shell within a TSO/E session
there was not enough memory left to do the binding. In these cases, we
resorted to running an hpj shell script under BPXBATCH and we were
always successful.
The Java program is now ready for execution under IMS.
3. Define resources to IMS
If the IVP is not already defined to the IMS system, you have to define the
DFSIVP32 program, the IVTCC transaction, and the IVPDB2 database to
the IMS GEN before invoking the program through an IMS message
region. (See IMS Installation Volume 1: Installation and Verification,
GC26-9429.)
Chapter 6. IMSAuto application build and execute 115

4. IMS message region preparation
Next you have to include the PDSE PGMLIB which contains the hpj
bound executables for the application, in the STEPLIB concatenation.
Also include the IMS Java Class Library and HPJ Class Libraries in the
STEPLIB (see Figure 77).
//STEPLIB DD DSN=IMS.SJIMSR.SDFSJLIB,DISP=SHR IMS CLASS LIBRARY
// DD DSN=HPJ390.SHPJMOD,DISP=SHR HPJ CLASS LIBRARY
// DD DSN=HPJ390.SHPOMOD,DISP=SHR HPJ CLASS LIBRARY
// DD DSN=IMS.SJIMSR.IVP.PGMLIB,DISP=SHRPDSE PGMLIB
// DD DSN=IMS.SJIMSR.PGMLIB,DISP=SHR PDS PGMLIB
// DD DSN=IMS.SJIMSR.SDFSRESL,DISP=SHRIMS RESLIB
Figure 77. IMS Message Region STEPLIB Concatenation
5. Run the IVP program
Logon onto your IMS system and enter “/FOR IVTCC”. Your input screen
for the IVTCC transaction should look like that in Figure 78.
Figure 78. IVP program input screen
116 IMS Version 7 and Java Application Programming
**************************************************
* IMS INSTALLATION VERIFICATION PROCEDURE *
**************************************************
TRANSACTION TYPE : CONVERSATIONAL
DATE : 09/01/00
PROCESS CODE (*1) : display
LAST NAME : last1
(*1) PROCESS CODE
ADD
DELETE
FIRST NAME : UPDATE
DISPLAY
EXTENSION NUMBER : TADD
END
INTERNAL ZIP CODE :
SEGMENT# :

If you run the transaction, your output screen should look like that in
Figure 79.
**************************************************
* IMS INSTALLATION VERIFICATION PROCEDURE *
**************************************************
Figure 79. IVP program output screen
TRANSACTION TYPE : CONVERSATIONAL
DATE : 09/01/00
PROCESS CODE (*1) :
LAST NAME : LAST1
(*1) PROCESS CODE
ADD
DELETE
FIRST NAME : FIRST1 UPDATE
DISPLAY
EXTENSION NUMBER : 8-111-1111 TADD
END
INTERNAL ZIP CODE : D01/R01
ENTRY WAS DISPLAYED SEGMENT# :
Chapter 6. IMSAuto application build and execute 117

118 IMS Version 7 and Java Application Programming

Chapter 7. VisualAge for Java IMS application development
In this section, we discuss the mechanics of using VisualAge for Java to
develop IMS Java programs. Although this section covers a step-by-step
approach to working with an application project in VisualAge for Java, it is not
intended to be a primer on using VisualAge for Java. The IMS customization
to support the Java environment is covered in Chapter 2, “Environment
customization” on page 23. Also, you can refer to Programming with
VisualAge for Java Enterprise Version 2, SG24-5264, for basic information.
7.1 IMS JAVA classes in VisualAge for Java Version 3.02
In addition to installing VisualAge for Java on your workstation, you also have
to install ET/390. You then need to customize the ET/390 component on your
workstation as described in Chapter 2, “Environment customization” on page
23. This customization allows your Java programs to be transferred to the
OS/390 mainframe and bound by the HPJ compiler so that you can run your
programs under IMS.
VisualAge for Java Version 3 for Windows NT was made available in October
1999. This release does not ship with the IMS Java Class Libraries. Because
you will compile your programs on the workstation in VisualAge for Java
environment, you have to import the IMS JAVA classes from the OS/390
system where IMS Java has been installed into VisualAge for Java. If you use
VisualAge for Java Version 3, follow the steps below to make the IMS Java
classes available on your workstation.
These classes are contained in the MVS Unix System Services file
/usr/lpp/ims/imsjava71/classes.zip.
Use the following procedure to import the classes:
1. Transfer the /usr/lpp/ims/imsjava71/classes.zip file to your workstation in
binary format. This file was installed into the MVS UNIX System Services
environment when you installed IMS V7.1 Java. You can perform the
transfer using NFS or FTP.
2. Unzip the classes.zip file into a workstation directory. We used a directory
called c:\IMS_Java_Classes. When unzipped, this zip file will create
classes in the following three sub-directories:
- c:\IMS_Java_Classes\com\ibm\ims\application
- c:\IMS_Java_Classes\com\ibm\ims\base
- c:\IMS_Java_Classes\com\ibm\ims\db
© Copyright IBM Corp. 2001 119

3. Start VisualAge for Java and go to the workbench (see Figure 80).
Figure 80. VisualAge for Java startup screen
4. Select Import from the File menu.
5. Select the Directory radio button in the SmartGuide Import dialog (see
Figure 81) and click the Next button.
120 IMS Version 7 and Java Application Programming

Figure 81. SmartGuide Import dialog
6. In the SmartGuide Import from a directory dialog, click the Directory
Browse button and navigate to the directory containing the unzipped class
files.
7. Select the directory c:\IMS_Java_Classes\com\ibm\ims\application and
click OK to return to the SmartGuide Import from a directory dialog (see
Figure 82).
8. Be sure that the boxes for class and resource are checked.
9. In the Project field, type IMS_Java_Class_Libraries.
Chapter 7. VisualAge for Java IMS application development 121

Figure 82. SmartGuide (Import from a directory) dialog — application
10.Click the Finish button. At this point the IMS application Java classes
have been imported into the IMS_Java_Class_Libraries Project.
11.Repeat steps 4 through 10 to import the IMS base and db classes (see
Figure 83 and Figure 84).
122 IMS Version 7 and Java Application Programming

Figure 83. SmartGuide (Import from a directory) dialog — base
Chapter 7. VisualAge for Java IMS application development 123

Figure 84. SmartGuide (Import from a directory) dialog — db
Once processing is complete, the Workbench can be used to view all of the
packages and classes within the IMS_Java_Class_Libraries (Figure 85).
124 IMS Version 7 and Java Application Programming

Figure 85. IMS_Java_Class_Libraries listing
Note: At this point, you have just finished importing IMS Java Class libraries
into VisualAge for Java.
Chapter 7. VisualAge for Java IMS application development 125

7.2 Writing, importing/exporting, and editing your program
This section covers the steps for writing, importing/exporting, and editing an
IMS Java program using VisualAge for Java.
In VisualAge for Java, your code and variables are placed in classes and
methods. Classes are grouped into packages and packages are grouped into
projects.
You can follow these steps if you want to create a new Project with new IMS
Java classes:
1. From the menu bar, click Selected -> Add -> Project.
Supply a new project name (you could use IMS_Java_Project), then click
Finish (see Figure 86).
Figure 86. SmartGuide (Add Project dialog)
126 IMS Version 7 and Java Application Programming

2. With the project name highlighted, click Selected -> Add -> Package.
Supply a new package name (you could use IMSJavaPGM), and click
Finish (see Figure 87). You will get a message warning you that Java
classes are usually in lower case, click Proceed.
Figure 87. SmartGuide (Add Package dialog)
Chapter 7. VisualAge for Java IMS application development 127

3. To add the IMSJavaPGM program, with the package name highlighted,
click Selected -> Add -> Class (see Figure 88).
Figure 88. SmartGuide Create Class dialog
4. On the SmartGuide Create Class dialog (see Figure 88), indicate that the
name of the new class is IMSJavaPGM. Make sure that Compose the
class visually is not checked. Then click Finish (see Figure 89).
128 IMS Version 7 and Java Application Programming

Figure 89. The newly created class: IMSJavaPGM
5. Be sure to add the following import statements to your class:
- import com.ibm.ims.application.*;
- import com.ibm.ims.base.*;
- import com.ibm.ims.db.*;
Chapter 7. VisualAge for Java IMS application development 129

6. Add a method called main (see Figure 90) with contents similar to those
shown in Figure 91, then add other application specific Java classes and
methods as appropriate.
Figure 90. SmartGuide Create Method dialog
130 IMS Version 7 and Java Application Programming

Figure 91. Workbench showing newly added method
For our testing we did not create any new IMS Java programs. The programs
we used for testing are part of the IMS Auto Dealership application (see
Appendix I, “Dealership sample application” on page 357). This is an IMS
online transaction, IMSAuto, that can be used to perform six different
functions against a full function DEALER database.
We imported the Java source code for the Auto Dealership, IMSAuto, from
our workstation into the VA-JAVA Dealership Project using the methodology
employed earlier to import the distributed IMS Java Classes.
Chapter 7. VisualAge for Java IMS application development 131

The Dealership Project consists of 2 packages: dealership.application, and
dealership.database. (See Figure 92).
Figure 92. Imported IMS Java classes
132 IMS Version 7 and Java Application Programming

To expand a package or a class, click the “+” sign in front of a specific class.
(See Figure 93 and Figure 94.)
Figure 93. Workbench showing expansion of classes
Chapter 7. VisualAge for Java IMS application development 133

Figure 94. Workbench showing modifiable source code
Click a field or a method of any class to edit the Java source code.
Note
Notice in Figure 94 the use of the System.out.println instruction which we
used during debugging of the application. (These displays are sent to a
dynamically allocated sysout DD in the IMS message processing region.
The datasets are named SYS00001, SYS00002 etc.)
When you are finished editing one object, click the next object to be edited
and a popup box will ask “Text has been modified - save changes?” You can
reply Yes, No, or Cancel. Another way to save an edited object is to select
Save from the Edit Menu.
134 IMS Version 7 and Java Application Programming

When you save, VA-JAVA will automatically compile the object and indicate if
there are errors. If you Save with errors, a red “X” will appear just to the left of
the object name (see Figure 95).
Figure 95. Workbench showing a method with an error
Javadoc can be produced for a project, a package, or a class within VA-JAVA
by highlighting the object and from the menu bar clicking Selected ->
Document -> GenerateJavadoc. You will be asked to provide a Directory for
Javadoc output which is in HTML format and can easily be viewed or printed
(see Figure 96).
Chapter 7. VisualAge for Java IMS application development 135

Figure 96. Javadoc option screen
7.3 Exporting your program for execution
To export your program for execution under IMS V7.1, you have to set up
ET/390. Additionally, you have to set up the environment for the project by
following these steps:
1. With the Dealership Project highlighted, click Selected -> Tools -> ET/390
-> Properties.
136 IMS Version 7 and Java Application Programming

2. In the ET/390 Properties SmartGuide for object Dealership, you initially
see the properties you set up for the VA-JAVA workspace. You could
override some of them here if there were some attributes that were
specific to this project.
We used Host SC47. O: (TEXT access) and P: (binary access) were
connected to the /u/imsres4 directory under the MVS USS HFS, the HFS
mount point on the SC47 Host was /u/imsres4, and the directory for class
files was established as O:\dealership (/u/imsre4/dealership).
Figure 97. ET/390 Properties for object Dealership
3. In the left part of the window (see Figure 97), click the plus sign next to
Export and Bind Session.
4. Click Bind Options to view the bind options for this project.
5. You can have a development and a production set of bind options (see
Figure 98)for the project. Click the radio button next to the environment for
which you are compiling (we used Development).
Chapter 7. VisualAge for Java IMS application development 137

Figure 98. ET/390 Properties for object Dealership (Bind Options)
Once the ET/390 setup is complete, the NFS connections are defined and
working properly, and your coding is completed, you can begin to export Java
source or Java class files from the workstation to the MVS USS HFS.
1. From the workbench, with the project, package, or class name highlighted
(see Figure 99), click Export from the File Menu.
138 IMS Version 7 and Java Application Programming

Figure 99. Workbench (Administrator) menu
2. Select the Directory radio button in the SmartGuide Export dialog (see
Figure 100) and click the Next button.
Chapter 7. VisualAge for Java IMS application development 139

Figure 100. SmartGuide Export dialog
3. In the SmartGuide Export to a directory dialog (see Figure 101), click the
Directory Browse button and navigate to the directory to which the Java
object should be exported.
140 IMS Version 7 and Java Application Programming

Figure 101. SmartGuide Export to a directory dialog
4. Click the appropriate boxes under What do you want to export? Using
.class will export only the Java bytecode, and .java will export only the
Java source code. We found that clicking resource to export
application-external class files (resources) took an extremely long time
and was not necessary. You can also click the desired Options boxes. We
used the Include debug attributes in .class files option. Occasionally we
used the Overwrite existing files without warning option but preferred to
get a notification.
Chapter 7. VisualAge for Java IMS application development 141

Note
Note that you must pay attention to and remember that .class and resource
files must be exported/imported as binary; and .java files must be
exported/imported as TEXT files. Be sure to use the appropriate network
drive.
5. Click Finish and the exporting starts. If you did not click the Overwrite
existing files without warning option, you will get a pop-up box asking Do
you want to overwrite it? You can reply Yes, Yes To All, No, or Cancel. If
you choose one of the Yes replies, you will see a message at the bottom of
the window indicating the object currently being exported (Figure 102).
Figure 102. Duplicate name error message
6. Repeat steps 1 through 5 to export individual classes, whole packages, or
entire projects.
7.4 Preparing your program for execution
To bind the exported VA-JAVA program bytecode, you must use the High
Performance Java (HPJ) compiler. The hpj command can be executed
interactively under the OMVS shell or inside a shell script executed from a
BPXBATCH job. Because of TSO storage limitations, we were forced to use a
batch BPXBATCH job (see Figure 103) to bind the IMSAuto bytecode into
executable code.
142 IMS Version 7 and Java Application Programming

We used the shell script in Figure 104 on page 144 to do the HPJ compile
and bind only. For illustration purposes, we also created and ran the shell
script in Figure 105 on page 145, which executes one script to do the
IMSAuto Java class compiles (Figure 106 on page 146); and we used another
script to do the HPJ compile and bind (Figure 107 on page 147).
//AUTOHPJ JOB (999,POK),’ITSO IMS TEAM’,MSGCLASS=U,CLASS=A,
// NOTIFY=&SYSUID,TIME=1440,REGION=0M
//* ------------------------------------------------------------------
//* EXECUTE SCRIPT
//* ------------------------------------------------------------------
//UXCALL EXEC PGM=BPXBATCH,REGION=0M,
// PARM=’SH /u/imsres4/Dealerhpj.sh.standalone’
//STEPLIB DD DISP=SHR,DSN=CEE.SCEERUN
//STDENV DD DUMMY
//STDIN DD DUMMY
//************************************* THE OUTPUT *********
//STDOUT DD PATH=’/u/imsres4/&SYSUID..autohpj.a082500.eout’,
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),PATHMODE=SIRWXU
//************************************* THE ERRORS *********
//STDERR DD PATH=’/u/imsres4/&SYSUID..autohpj.a082500.eerr’,
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),PATHMODE=SIRWXU
//************************************* THE SYSOUT *********
//SYSPRINT DD SYSOUT=*
//* ------------------------------------------------------------------
//* COPY RESULT(HFS) TO SYSOUT
//* ------------------------------------------------------------------
//HFS2PRT EXEC PGM=IKJEFT01,DYNAMNBR=300,COND=EVEN
//SYSTSPRT DD SYSOUT=*
//HFSOUT DD PATH=’/u/imsres4/&SYSUID..autohpj.a082500.eout’
//HFSERR DD PATH=’/u/imsres4/&SYSUID..autohpj.a082500.eerr’
//STDOUTL DD SYSOUT=*,DCB=(RECFM=VB,LRECL=6140,BLKSIZE=0)
//STDERRL DD SYSOUT=*,DCB=(RECFM=VB,LRECL=6140,BLKSIZE=0)
//SYSPRINT DD SYSOUT=*
//SYSTSIN DD *
OCOPY INDD(HFSOUT) OUTDD(STDOUTL)
OCOPY INDD(HFSERR) OUTDD(STDERRL)
/*
//
Figure 103. BPXBATCH job to execute HPJ-only shell script
Chapter 7. VisualAge for Java IMS application development 143

# ##################################################################
# CREATED:
# ITSO 7/28/00 - execute only HPJ binder for ITSO DEALER APPL
# ##################################################################
echo BEGIN Dealerhpj.sh.standalone
date
cd
cd u/imsres4
. profile.imsjava
. profile.imsres4
cd
cd usr/lpp/hpj/bin
. profile.hpj
#
export IMSJAVA=/usr/lpp/ims/imsjava71
export IMSJDLL=/usr/lpp/ims/imsjava71/imsjava.jll
export IMSCLIB=/usr/lpp/ims/imsjava71/libJavTDLI.dll
export IMSHPJ=/usr/lpp/hpj/lib
export PATH=$PATH:/usr/lpp/hpj/bin
echo IMSJAVA : $IMSJAVA
echo IMSJDLL : $IMSJDLL
echo IMSCLIB : $IMSCLIB
echo IMSHPJ : $IMSHPJ
echo PATH : $PATH
#
cd
cd /u/imsres4
#
hpj dealership.application.IMSAuto \
-main=dealership.application.IMSAuto \
-o=”//’IMS.SJIMSR.IVP.PGMLIB(IMSAUTO)’” -alias=IMSAUTO \
-target=IMS \
-lerunopts=”ENVAR(CLASSPATH=$IMSJAVA:$IMSJDLL:$IMSCLIB:$IMSHPJ)” \
-verbose \
-include=dealership.application.DealerDatabaseView \
-exclude=com.ibm.ims.db.* \
-exclude=com.ibm.ims.application.* \
-exclude=com.ibm.ims.base.*
#
date
echo END Dealerhpj.sh.standalone
Figure 104. /u/imsres4/Dealerhpj.sh.standalone -— HPJ-only shell script
144 IMS Version 7 and Java Application Programming

# ###############################################################
# CREATED:
# ITSO 8/10/00 - SCRIPT SHELL TO javac THE JAVA CODE AND
# hpj BIND THE BYTECODE INTO AN EXECUTABLE
# FOR THE ITSO AUTO DEALER APPLICATION
# ###############################################################
echo START Dealerscript.ver3 TO COMPILE AND BIND AUTO/DEALER APPL
date
cd
cd u/imsres4
. profile.imsjava
. profile.imsres4
cd
cd usr/lpp/hpj/bin
. profile.hpj
cd
cd u/imsres4
Dealerjavac.sh.ver3
Dealerhpj.sh.ver3
Date
echo END Dealerscript.ver3 TO COMPILE AND BIND AUTO/DEALER APPL
Figure 105. u/imsres4/Dealerscript.ver3 — script to execute 2 other scripts
Chapter 7. VisualAge for Java IMS application development 145

# ###############################################################
# CREATED:
# NGS 08/10/00 - javac compile of ITSO DEALER APPL
# ###############################################################
echo BEGIN Dealerjavac.sh.ver3
cd
cd u/imsres4
. profile.imsjava
. profile.imsres4
cd
cd /u/imsres4
javac dealership/database/*.java -verbose
javac dealership/application/AcceptOrderInput.java -verbose
javac dealership/application/Cancelled.java -verbose
javac dealership/application/CancelOrderInput.java -verbose
javac dealership/application/CarFound.java -verbose
javac dealership/application/DealerDatabaseView.java -verbose
javac dealership/application/ErrorMessage.java -verbose
javac dealership/application/FindACarInput.java -verbose
javac dealership/application/InputMessage.java -verbose
javac dealership/application/ListModelsInput.java -verbose
javac dealership/application/ModelDetails.java -verbose
javac dealership/application/ModelList.java -verbose
javac dealership/application/OrderAccepted.java -verbose
javac dealership/application/OutputMessage.java -verbose
javac dealership/application/RecordASaleInput.java -verbose
javac dealership/application/SalesRecord.java -verbose
javac dealership/application/ShowModelDetailsInput.java -verbose
javac dealership/application/IMSAuto.java -verbose
echo END Dealerjavac.sh.ver3
# ##########################################################
# #### FOLLOWING javac COMPILE ORDER WILL NOT WORK
# #### database/*.java MUST BE COMPILED FIRST
# #### application/*.java MUST BE COMPILED SECOND
# #### IMSAuto.java HAS TO BE COMPILED LAST TO WORK
# ##########################################################
# javac dealership/database/*.java -verbose
# javac dealership/application/*.java -verbose
Figure 106. u/imsres4/Dealerjavac.sh.ver3 — javac compile script
146 IMS Version 7 and Java Application Programming

# ##################################################################
# CREATED:
# ITSO 8/10/00 - hpj binder for the ITSO DEALER APPL
#
# ##################################################################
echo BEGIN Dealerhpj.sh.ver3
export IMSJAVA=/usr/lpp/ims/imsjava71
export IMSJDLL=/usr/lpp/ims/imsjava71/imsjava.jll
export IMSCLIB=/usr/lpp/ims/imsjava71/libJavTDLI.dll
export IMSHPJ=/usr/lpp/hpj/lib
export PATH=$PATH:/usr/lpp/hpj/bin
echo IMSJAVA : $IMSJAVA
echo IMSJDLL : $IMSJDLL
echo IMSCLIB : $IMSCLIB
echo IMSHPJ : $IMSHPJ
echo PATH : $PATH
#
cd
cd u/imsres4
#
hpj dealership.application.IMSAuto \
-main=dealership.application.IMSAuto \
-o=”//’IMS.SJIMSR.IVP.PGMLIB(IMSAUTO)’” -alias=IMSAUTO \
-target=IMS \
-lerunopts=”ENVAR(CLASSPATH=$IMSJAVA:$IMSJDLL:$IMSCLIB:$IMSHPJ)” \
-verbose \
-include=dealership.application.DealerDatabaseView \
-exclude=com.ibm.ims.db.* \
-exclude=com.ibm.ims.application.* \
-exclude=com.ibm.ims.base.*
#
# ##### COMMENTED OUT - STATICALLY BIND OBJECTS INTO EXECUTABLE
#
# -exclude=com.ibm.ims.db.* \
# -exclude=com.ibm.ims.application.* \
# -exclude=com.ibm.ims.base.*
#
echo END Dealerhpj.sh.ver3
Figure 107. u/imsres4/Dealerhpj.sh.ver3 - HPJ binder script
Chapter 7. VisualAge for Java IMS application development 147

7.5 Executing your Java program in IMS
The Java program is now ready for execution in IMS. But the IMS
environment setup needs to be completed, as shown in Figure 108 on page
148, Figure 109 on page 149, and Figure 110 on page 150.
1. Define the necessary IMS Gen resources.
Stage1 Gen Input:
**********************************************************************
* IMSAUTO DEALERDB DEFINITION
**********************************************************************
DATABASE DBD=DEALERDB,ACCESS=UP HDAM/VSAM
**********************************************************************
* IMSAUTO NON-CONVERSATIONAL APPLICATION DEFINITION
**********************************************************************
APPLCTN PSB=IMSAUTO,PGMTYPE=TP HDAM/VSAM
Figure 108. Stage1 Gen input
148 IMS Version 7 and Java Application Programming
TRANSACT CODE=IMSAUTO,MODE=SNGL, X
MSGTYPE=(SNGLSEG,NONRESPONSE,1)

DBD Gen Input:
***********************************************************************
* DESCRIPTION OF DEALER DATABASE
* FOR ITSO SAMPLE APPLICATION
* DOCUMENTED IN IMS JAVA USER’S GUIDE
* ----------------------------------------
*
DBD NAME=DEALERDB,ACCESS=(HDAM,VSAM), X
RMNAME=(DFSHDC40,4,80,500)
*
DATASET DD1=DEALERDD,DEVICE=3330,MODEL=1,SIZE=4096
*
* DEALER - GENERAL INFORMATION (ROOT)
* ---------------------------------------
SEGM NAME=DEALER,PARENT=0,BYTES=94
FIELD START=01,BYTES=4,TYPE=C,NAME=(DLRNO,SEQ,U)
FIELD START=05,BYTES=30,TYPE=C,NAME=DLRNAME
*
* DEALER - MODEL INFORMATION
* ---------------------------------------
SEGM NAME=MODEL,PARENT=DEALER,BYTES=43
FIELD START=1,BYTES=2,TYPE=C,NAME=(MODTYPE,SEQ,U)
FIELD START=3,BYTES=10,TYPE=C,NAME=MAKE
FIELD START=13,BYTES=10,TYPE=C,NAME=MODEL
FIELD START=23,BYTES=4,TYPE=C,NAME=YEAR
FIELD START=27,BYTES=5,TYPE=P,NAME=MSRP
*
* DEALER - ORDER INFORMATION
* ---------------------------------------
SEGM NAME=ORDER,PARENT=MODEL,BYTES=127
FIELD START=1,BYTES=6,TYPE=C,NAME=(ORDNBR,SEQ,U)
FIELD START=50,BYTES=25,TYPE=C,NAME=LASTNME
FIELD START=75,BYTES=25,TYPE=C,NAME=FIRSTNME
*
* DEALER - SALES INFORMATION
* ---------------------------------------
SEGM NAME=SALES,PARENT=MODEL,BYTES=113
FIELD START=1,BYTES=8,TYPE=C,NAME=(SALDATE,SEQ,U)
FIELD START=9,BYTES=25,TYPE=C,NAME=LASTNME
FIELD START=34,BYTES=25,TYPE=C,NAME=FIRSTNME
FIELD START=94,BYTES=20,TYPE=C,NAME=STKVIN
*
* DEALER - STOCK INFORMATION
* ---------------------------------------
SEGM NAME=STOCK,PARENT=MODEL,BYTES=62
FIELD START=1,BYTES=20,TYPE=C,NAME=(STKVIN,SEQ,U)
FIELD START=37,BYTES=10,TYPE=C,NAME=COLOR
FIELD START=47,BYTES=5,TYPE=C,NAME=PRICE
FIELD START=53,BYTES=10,TYPE=C,NAME=LOT
*
DBDGEN
FINISH
END
Figure 109. DB2 Gen input
Chapter 7. VisualAge for Java IMS application development 149

PSB Gen Input:
***********************************************************************
* PSB: IMSAUTO
* IMSAUTO PROGRAM SPECIFICATION BLOCK FOR
* ITSO AUTO/DEALER IMS/JAVA APPLICATION
*
* IOPCB PCB TYPE=TP GENERATED AUTOMATICALLY FOR ONLINE TRAN
*
PCB TYPE=TP,MODIFY=YES ALTERNATE MODIFIABLE IOPCB
*
DEALPCB1 PCB TYPE=DB,DBDNAME=DEALERDB,PROCOPT=AP,KEYLEN=40
SENSEG NAME=DEALER,PARENT=0,PROCOPT=AP
SENSEG NAME=MODEL,PARENT=DEALER,PROCOPT=AP
SENSEG NAME=ORDER,PARENT=MODEL,PROCOPT=AP
SENSEG NAME=SALES,PARENT=MODEL,PROCOPT=AP
SENSEG NAME=STOCK,PARENT=MODEL,PROCOPT=AP
*
DEALPCB2 PCB TYPE=DB,DBDNAME=DEALERDB,PROCOPT=AP,KEYLEN=40
SENSEG NAME=DEALER,PARENT=0
SENSEG NAME=MODEL,PARENT=DEALER
SENSEG NAME=ORDER,PARENT=MODEL
SENSEG NAME=SALES,PARENT=MODEL
SENSEG NAME=STOCK,PARENT=MODEL
*
DEALPCB3 PCB TYPE=DB,DBDNAME=DEALERDB,PROCOPT=GOP,KEYLEN=6
SENSEG NAME=DEALER,PARENT=0
SENSEG NAME=MODEL,PARENT=DEALER
*
DEALPCB4 PCB TYPE=DB,DBDNAME=DEALERDB,PROCOPT=AP,KEYLEN=12
SENSEG NAME=DEALER,PARENT=0
SENSEG NAME=MODEL,PARENT=DEALER
SENSEG NAME=ORDER,PARENT=MODEL
*
DEALPCB5 PCB TYPE=DB,DBDNAME=DEALERDB,PROCOPT=GP,KEYLEN=14
SENSEG NAME=DEALER,PARENT=0
SENSEG NAME=MODEL,PARENT=DEALER
SENSEG NAME=SALES,PARENT=MODEL
*
DEALPCB6 PCB TYPE=DB,DBDNAME=DEALERDB,PROCOPT=GOP,KEYLEN=26
SENSEG NAME=DEALER,PARENT=0
SENSEG NAME=MODEL,PARENT=DEALER
SENSEG NAME=STOCK,PARENT=MODEL
*
PSBGEN LANG=ASSEM,CMPAT=YES,PSBNAME=IMSAUTO
END
Figure 110. PSB Gen input
150 IMS Version 7 and Java Application Programming

2. IMS message region preparation
In the message region STEPLIB concatenation you have to include the
PDSE PGMLIB which contains the HPJ bound executables for the
IMSAuto application. Also include the IMS Java Class Library and HPJ
Class Libraries in the STEPLIB (see Figure 111).
//STEPLIB DD DSN=IMS.SJIMSR.SDFSJLIB,DISP=SHR IMS CLASS LIBRARY
// DD DSN=HPJ390.SHPJMOD,DISP=SHR HPJ CLASS LIBRARY
// DD DSN=HPJ390.SHPOMOD,DISP=SHR HPJ CLASS LIBRARY
// DD DSN=IMS.SJIMSR.IVP.PGMLIB,DISP=SHRPDSE PGMLIB
// DD DSN=IMS.SJIMSR.PGMLIB,DISP=SHR PDS PGMLIB
// DD DSN=IMS.SJIMSR.SDFSRESL,DISP=SHRIMS RESLIB
Figure 111. IMS message region STEPLIB concatenation
3. IMSAuto transaction input
The IMSAuto executable contains methods that:
- List all car models in the DEALER database.
- Show the details for a specific car model in the DEALER database.
- Find a specific type, model and color of car in the DEALER database.
- Accept an order for a car with a specific vehicle identification number.
- Cancel a specific order in the DEALER database.
- Record a specific car sale in the DEALER database.
Various techniques can be used to queue IMS transaction input messages.
Since our IMSAuto application had not existed prior to our testing, no MFS
code or any other method for message inputting existed. So, we chose to use
the simplest method to test the IMSAuto transaction — native 3270 IMS
terminal input and output.
Note
Note: We did install and utilize successfully the IMS Client for Java. This
product requires the IMS Connector.
The following code listings show the IMSAuto transaction input messages for
the various IMSAuto command codes. After each input message we have
listed the corresponding output message, extracted from the x’03’ log record,
which was sent back to the terminal.
Chapter 7. VisualAge for Java IMS application development 151

LISTMODELS
INPUT MESSAGE:
123456789012345678
IMSAUTO LISTMODELS
OUTPUT MESSAGE:
....15HONDA ACCORD 200016HONDA CIVIC 200017HONDA PRELUDE 20
0003FFCDDCC44444CCCDDC4444FFFFFFCDDCC44444CCECC44444FFFFFFCDDCC44444DDCDECC444FF
00091586541000001336940000200016865410000039593000002000178654100000795344500020
0018HONDA CR-V 200015HONDA ACCORD 200016HONDA CIVIC 2000
FFFFCDDCC44444CD6E444444FFFFFFCDDCC44444CCCDDC4444FFFFFFCDDCC44444CCECC44444FFFF
00188654100000390500000020001586541000001336940000200016865410000039593000002000
17HONDA PRELUDE 200018HONDA CR-V 200011TOYOTA AVALON 200012
FFCDDCC44444DDCDECC444FFFFFFCDDCC44444CD6E444444FFFFFFEDEDEC4444CECDDD4444FFFFFF
17865410000079534450002000188654100000390500000020001136863100001513650000200012
TOYOTA CAMRY 200013TOYOTA SOLARA 200014TOYOTA 4RUNNER 200001FO
EDEDEC4444CCDDE44444FFFFFFEDEDEC4444EDDCDC4444FFFFFFEDEDEC4444FDEDDCD444FFFFFFCD
36863100003149800000200013368631000026319100002000143686310000494555900020000166
RD TAURUS 200002FORD ESCORT 200003FORD
DC444444ECEDEE4444FFFFFFCDDC444444CECDDE4444FFFFFFCDDC444444 etc...
940000003149420000200002669400000052369300002000036694000000
SHOWMODELDETAIL
INPUT MESSAGE:
123456789012345678901234567890
IMSAUTO SHOWMODELDETAILS 11
OUTPUT MESSAGE:
11TOYOTA AVALON 200034000002700300225
FFEDEDEC4444CECDDD4444FFFFFFFFFFFFFFFFFFFFF
1136863100001513650000200034000002700300225
152 IMS Version 7 and Java Application Programming

FINDACAR
INPUT MESSAGE:
123456789012345678901234567890123456789012345678901234567890123456789012
IMSAUTO FINDACAR TOYOTA AVALON 20003000040000SILVER
OUTPUT MESSAGE:
....GGGG TOYOTA INC. TOYOTA AVALON 2000TOYOLOT 71HHHH TOYOTA
0000CCCC4EDEDEC4CDC444444444444444EDEDEC4444CECDDD4444FFFFEDEDDDE4FFCCCC4EDEDEC4
0003777703686310953B000000000000003686310000151365000020003686363071888803686310
INC. TOYOTA AVALON 2000TOYOLOT 81IIII TOYOTA INC.
CDC444444444444444EDEDEC4444CECDDD4444FFFFEDEDDDE4FFCCCC4EDEDEC4CDC4444444444444
953B000000000000003686310000151365000020003686363081999903686310953B000000000000
TOYOTA AVALON 2000TOYOLOT 91.....................
44EDEDEC4444CECDDD4444FFFFEDEDDDE4FF000000000000000000000 etc...
003686310000151365000020003686363091000000000000000000000
ACCEPTORDER
INPUT MESSAGE:
12345678901234567890123456789012345678901234567890123456789012
IMSAUTO ACCEPTORDER T0074D08252000TOYOVIN 300711T1T1T1
OUTPUT MESSAGE:
Order updated
D98894A988A88
6945904741354
CANCELORDER
INPUT MESSAGE:
12345678901234567890123456789012345678
IMSAUTO CANCELORDER T0074D3007
OUTPUT MESSAGE:
1
F444
1000
Chapter 7. VisualAge for Java IMS application development 153

RECORDASALE
INPUT MESSAGE:
12345678901234567890123456789012345678901234567890123456789012345678901234
IMSAUTO RECORDASALE 30071108252000DORKLE DARLING
5678901234567890123456789012345678901234567890123456789012345678901234567
1111 MAIN ST ANYWHERE USASELLER9999TOYOVIN 300711T1T1T1
OUTPUT MESSAGE:
Sales recorded
E898A498899888444444444444444444444444444444444444444444444444444444444444444444
21352095369454000000000000000000000000000000000000000000000000000000000000000000
154 IMS Version 7 and Java Application Programming

Part 3. Debugging and problem determination
This part of the book describes debugging and problem determination.
It contains the following chapters:
Chapter 8, “Diagnostic techniques” on page 157
Chapter 9, “Development limitations” on page 165
© Copyright IBM Corp. 2001 155

156 IMS Version 7 and Java Application Programming

Chapter 8. Diagnostic techniques
8.1 IMSTrace
This chapter describes various diagnostic techniques that can be used to
help debug your Java applications.
IMSTrace provides you with the ability to debug your Java applications by
tracing, or documenting, the flow of control throughout your application. By
having the ability to set up tracepoints throughout your applications for
output, you can isolate problem areas and, therefore, know where to make
adjustments to produce the results you expect. In addition, because
IMSTrace supports writing input parameters and results, and the IMS Java
library provided routines use this feature, you can verify that correct results
occur across method boundaries.
8.1.1 Initiating IMSTracing
To debug with IMSTrace, you must first turn on the tracing function by setting
the IMSTrace.traceOn variable to true. Because tracing does not occur until
this variable is set, it is best to do so within a static block of the
IMSApplication subclass. Then, you must decide how closely you want to
trace the IMS Java library’s flow of control, as well as how much tracing you
want to add to your application code.
You determine the amount of tracing in the IMS Java library by setting the
value of IMSTrace.libTraceLevel to one of its predefined values. By default,
this value is set to IMSTrace.TRACE_EXCEPTIONS, which traces the
construction of IMS-Java-library-provided exceptions. IMSTrace also defines
constants for three types of additional tracing. These constants provide
successively more tracing from IMSTrace.TRACE_CTOR1 (level one tracing
of constructions) to IMSTrace.TRACE_DATA3 (level three tracing of data).
8.1.2 Setting up tracing for the IMS Java library routines
To turn on the tracing shipped with the IMS Java library routines:
1. Turn on the flag enabling tracing. (It is turned off by default.)
IMSTrace.traceOn = true;
2. Set the level of tracing for the IMS Java library routines. In this example,
the constructors are traced, as is the entry and exit of level one methods:
IMSTrace.libTraceLevel = IMSTrace.TRACE_METHOD1;
© Copyright IBM Corp. 2001 157

3. Set an output stream (a print stream or a character output writer) as the
current trace stream.
For example:
a. Set the system error stream as the current trace stream:
catch (Exception e) {
// Use standard error if the file couldn’t be opened for writing
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
IMSApplication subclass main routine:
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();
}
}
8.1.3 Adding trace statements to your application
You can add trace statements to your application, similar to those provided by
the IMS Java Library, by defining an integer variable that you test prior to
writing trace statements. Using a variable other than IMSTrace.libTraceLevel
enables you to control the level of tracing in your application independently of
the tracing in the IMS Java library. For example, you can turn off the tracing of
IMS Java library routines by setting IMSTrace.libTraceLevel to zero while still
tracing your application code.
158 IMS Version 7 and Java Application Programming

Follow these steps to add tracing to your application code:
1. Define an integer variable to contain the trace level for
application-provided code:
public class IMSAuto extends IMSApplication {
public int application TraceLevel = IMSTrace.TRACE_CTOR3;
2. Call IMSTrace routines to trace methods, parameters, and return values
as necessary:
public class IMSAuto extends IMSApplicatio {
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();
}
public void doBegin() throws IMSException {
if(IMSAuto.applicationTraceLevel >= IMSTrace.TRACE_METHOD1)
IMSTrace.currentTrace().logEntry("IMSAuto.doBegin");
try {
//Add code here ...
}
finally {
if(IMSAuto.applicationTraceLevel >= IMSTrace.TRACE_METHOD1)
IMSTrace.currentTrace().logExit("IMSAuto.doBegin");
}
}
public String method1(String parm ){
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 {
if (IMSAuto.applicationTraceLevel >= IMSTrace.TRACE_METHOD2)
IMSTrace.currentTrace().logExit(“IMSAuto.method1”);
}
return result;
}
}
Chapter 8. Diagnostic techniques 159

8.2 Writing your Java code with problem detection in mind
This section describes some features that you could include in your programs
to simplify problem detection in the program. However, if you are writing
code, or have the opportunity to add to existing code, you might think about
adding some of these features.
8.2.1 Java sample tracing
There are a number of ways you might consider adding debug tracing to your
code. In this section we offer some guidance on writing trace facilities.
8.2.2 Trace started using a program argument
This feature traces processing at a very high level. The trace is displayed in
the standard output, which is useful for tracing a single request. However, for
tracing multiple requests, a trace file is required to allow detailed analysis.
When the program being traced has several threads, one of the parameters
that must be traced is the thread identifier that is running the request. This
enables the trace to detect problems in thread synchronization.
8.2.3 Debugging trace method in each class
Each class in your program might provide a trace function. There are a
number of alternatives to activate such a trace, such as: Having the trace
code compiled into the main program function, and activated by a trace flag.
For example, each class might test the value of the flag on initialization (that
is, in the constructor) to determine whether to use the trace method. The flag
could also specify different levels of tracing, such as method calls, or tracing
the contents of variables. The flag could be set in a properties file. To avoid a
large performance impact using this technique, class initialization could set a
local flag which then dictates whether to use tracing. For example, you could
do something like the following:
int tracing_flag = 0; // initialize trace flag
tracing_flag = System.getProperty("traceflag");
...
if (tracing_flag > 0) trace(tracing_flag);
Have the trace code compiled into a debug version of the software.
160 IMS Version 7 and Java Application Programming

This is a lower level of trace, which is useful during unit test or for debugging
of a problem. Although Java does not have conditional compilation, most
Java compilers will not include unreachable code in a class. Therefore you
could set up a static variable to turn debugging on or off, and have the call to
the debug method dependent on the setting of that flag. To compile a version
of your software without debugging code, simply set the flag to false, and
compile.
8.2.4 Handling exceptions
Java provides an elegant solution to the problem of error management of
exceptions. Exceptions enable you to write the main flow of your code and
deal with exceptional cases outside the mainline code. In fact, OS/390 uses a
similar architecture for its error handling in Functional Recovery Routines.
However, exceptions do not spare you the effort of doing the work of
detecting, reporting, and handling errors.
We have many examples of Java code where exceptions are caught, but no
action is taken in the catch phrase. This should never be allowed. At a
minimum, the exception should be traced, preferably to a file (note that
writing to a file can also cause an exception, which you should be prepared to
deal with). Following is a short sample of how to trace the complete
information from an exception:
/**
* This method prints an exception to the log file.
* @param ex java.lang.Exception
*/
public static void printException(Exception ex) {
java.text.SimpleDateFormat formatter = new
java.text.SimpleDateFormat(DATE);
java.util.Date date = new java.util.Date();
String dateString = formatter.format(date);
try {
getOutput().write(dateString);
} catch (IOException ioe){
ioe.printStackTrace();
}
ex.printStackTrace(new PrintWriter(getOutput())) ;
try {
getOutput().flush();
} catch (IOException ioe){
ioe.printStackTrace();
}
}
Chapter 8. Diagnostic techniques 161

The output is defined as follows:
/**
* This method creates an outputWriter to file named LSI115.
* @param ex java.lang.Exception
*/
public static Writer getOutput() {
if (fileName == null )
fileName = "LSI001.LOG" ;
try {
if (output == null)
output = (Writer)new FileWriter(fileName);
} catch (IOException ioe) {
ioe.printStackTrace();
}
return output;
}
Every time an exception is caught, we have to trace the exception as follows:
} catch (Exception e){
Log.printException(e);
return ;
}
Sample output from the log file is as follows:
1999.August.19 11:36:02 java.lang.ArrayIndexOutOfBoundsException
java.lang.Throwable()
java.lang.Exception()
java.lang.RuntimeException()
java.lang.IndexOutOfBoundsException()
java.lang.ArrayIndexOutOfBoundsException()
void fileio.PortableFileReader.main(java.lang.String [])
void fileio.PortableFileReader.main(java.lang.String [])
162 IMS Version 7 and Java Application Programming

8.3 Diagnosing problems with Java on OS/390
For severe problems with running, IMS Java generates two types of files in
the file system:
.CEEDUMP.yyyymmdd.hhmmss.nnnnnnnn
.JAVADUMP.yyyymmdd.hhmmss.nnnnnnnnnn
The CEEDUMP file is a language environment dump. A very useful section of
this dump file is the “traceback”, which traces function calls and reports
where the exception that caused the dump took place.
8.4 Diagnosing LE (Language Environment) messages and abends
Here are some common CEL messages:
CEE3201S - Indicates ABEND0C1
CEE3204S - Indicates ABEND0C4
CEE32xxS - Indicates ABEND0Cy
- where y is the hex equivalent of decimal xx
CEE3250C - Indicates some non-0Cx ABEND occurred
CEE0802C and CEE0813S - Error with HEAP storage (normally a user
problem)
The following describes the LE Condition Token (Feedback Code)
- Example: 00030C84 59C3C5C5 xxxxxxxx
- 0003 Severity
- 0000 Informational
- 0001 Warning (W)
- 0002 Error (E)
- 0003 Severe (S)
- 0004 Critical (C)
0C84 Hex message number (3204)
59 Flags (ignore)
C3C5C5 Prefix (Facility ID)
xxxxxxx Used internally
This token represents Message CEE3204S.
Chapter 8. Diagnostic techniques 163

164 IMS Version 7 and Java Application Programming

Chapter 9. Development limitations
This chapter lists several development limitations you may encounter:
Use of AIB requires PCBNAMES in PSB.
Cannot call COBOL subroutines.
Must be single-threaded.
Use PDSE VS HFS FILE.
PDSE in STEPLIB concatenation (may impact existing JCL inserting a
database record).
Inserting database record.
Be sure to refer to the latest IMS Java IBM documentation if you need more
details on any of the above topics.
© Copyright IBM Corp. 2001 165

166 IMS Version 7 and Java Application Programming

Part 4. Appendices
This part of the book contains ten useful appendices for reference:
Appendix A, “IMS Java package” on page 169
Appendix B, “Debugging and problem determination” on page 301
Appendix C, “IMS abend codes” on page 305
Appendix D, “IMS Java tracing facilities” on page 307
Appendix E, “IVP application — Java source (Java to DLI version)” on
page 311
Appendix F, “IVP application — Java source (JDBC version)” on page 325
Appendix G, “IVP application — COBOL source” on page 339
Appendix H, “Installing the IVP Phone application” on page 351
Appendix I, “Dealership sample application” on page 357
Appendix J, “Options for the hpj command” on page 385
© Copyright IBM Corp. 2001 167

168 IMS Version 7 and Java Application Programming

Appendix A. IMS Java package
The IMS Java package contains the following packages and is installed with
IMS Version 7 via SMP/E:
1. The package com.ibm.ims.base (Base package), provides the lowest level
of access. This package provides Java method calls which have been
written to match the DL/I calls currently supported in the other languages.
(CEETDLI for C/C++, PLITDLI for PL/I).The mapping is achieved using
Java Native Interface calls (JNI) from Java to the CEETDLI interface.
Since Java does not have structures as do these other languages, the
base package includes the classes AIB, DBPCB, and IOPCB to map to the
data of these structures. The base package is provided primarily as an
implementation vehicle for the high level packages com.ibm.ims.db
(the db package) and com.ibm.ims.application (the application package).
2. The package com.ibm.ims.db (the db package) provides high level access
to IMS databases. This access includes full support for applications to
build Segment Search Arguments (SSAs), and to use these SSA objects
to retrieve, insert, update, and delete segments.
3. The package com.ibm.ims.application (Application package) provides
higher level access to many of the IMS transaction and system services.
This includes Sync point services and access to the message queues.
4. The following class documentation can be found in the directory
/usr/lpp/ims/imsjava71/docs/api.zip. You can use NFS or FTP to transfer
the file to a workstation to unzip and use it as a reference for the individual
classes. When you unzip the api file it will create .html files containing all
the class documentation.
A.1 Contents of com.ibm.ims.application package
The com.ibm.ims.application package contains the following classes:
com.ibm.ims.application.IMSApplication
com.ibm.ims.application.IMSErrorMessages
com.ibm.ims.application.IMSFieldMessage
com.ibm.ims.application.IMSMessageQueue
com.ibm.ims.application.IMSTransaction
© Copyright IBM Corp. 2001 169

A.2 Class com.ibm.ims.application.IMSApplication
Constructors
Methods
java.lang.Object
+----com.ibm.ims.application.IMSApplication
public abstract class IMSApplication extends Object
IMSApplication is the abstract base class for all Java IMS programs. Each
application receives control in its static main method, where it is responsible to
create an instance of its class and call the begin method of its base class,
IMSApplication. The begin method does application setup, invokes its
abstract doBegin method, and upon its return, terminates the application. Java
application programs implement their entire application from within their
doBegin override.
IMSApplication ()
protected IMSApplication()
Creates a new IMSApplication object.
begin ()
public final void begin()
This will run the application. It first sets up the environments for IMS and
JDBC/SQLJ driver, then invokes its abstract doBegin method, and upon its
return, terminates the application. Any exception caught from running the
application will result in abending the transaction.
do Begin()
public abstract void doBegin() throws IMSException
Implementation of the IMS application. All application programs should
override this method and define their own application here.
Throws: IMSException
170 IMS Version 7 and Java Application Programming

programName ()
public String programName() throws IMSException
Returns the application program name.
Returns: The application program name.
Throws: IMSException if a non-blank status code is returned from the
system call.
A.3 Class com.ibm.ims.application.IMSErrorMessages
Constructors
Methods
Note
The application should handle all IMS exception properly. All
uncaught exceptions will result in abending the transaction in the
begin method.
java.lang.Object
+----java.util.ResourceBundle
+----java.util.ListResourceBundle
public class IMSErrorMessages extends ListResourceBundle
This class contains all the error messages used in the
com.ibm.ims.application package.
IMSErrorMessages ()
public IMSErrorMessages()
Instantiates a new IMSErrorMessages object.
getContents ()
protected Object[ ][ ] getContents()
Returns the contents of the error messages.
Overrides: getContents in class ListResourceBundle
Appendix A. IMS Java package 171

getIMSBundle ()
public static IMSErrorMessages getIMSBundle()
Returns the contents of the error messages.
A.4 Class com.ibm.ims.application.IMSFieldMessage
java.lang.Object
+----com.ibm.ims.base.DLIBaseSegment
+----com.ibm.ims.application.IMSFieldMessage
public abstract class IMSFieldMessage extends DLIBaseSegment
IMSFieldMessage is an abstract base class for objects representing messages
in an IMS message queue. These IMSFieldMessage subclasses provide the
mapping between the data in the message and access functions on the class.
User applications can reference the fields of the message by field index or by
field name and utilize a wide range of data conversion functions provided in
the base class DLIBaseSegment.
To provide the mapping, the subclasses must provide an array of DLITypeInfo
objects for the fields in the message as an argument to the IMSFieldMessage
constructor. By doing so, the DLIBaseSegment class knows the layout of each
field in the message and can access as well as update each of these fields.
IMSFieldMessage is used to define either normal input and output messages
(usually a separate subclass for each) or to define a data area called the
Scratch Pad Area (SPA). The SPA is used in conversational transactions to
store information between one step of the conversation and the next. To
define a SPA message, the IMSFieldMessage subclass sets isSPA to true on
the IMSFieldMessage constructor.
Note
Fields of type CHAR or VARCHAR will be encoded using the platform's default
character encoding. If another encoding is desired, invoke the inherited
setDefaultEncoding method of the IMSFieldMessage class, which isused to
specify the character encoding for all character data in a message.
A typical IMSFieldMessage subclass for an input message should look similar to
Figure 112.
172 IMS Version 7 and Java Application Programming

Variables
public class InputMessage extends com.ibm.ims.application.IMSFieldMessage {
static final DLITypeInfo[] segmentInfo = {
new DLITypeInfo("Field1", DLITypeInfo.CHAR, 1, 10),
new DLITypeInfo("Field2", DLITypeInfo.INTEGER, 11, 4),
new DLITypeInfo("Field3", DLITypeInfo.SMALLINT, 15, 2)
};
public MySegment() {
super(segmentInfo, 16, false);
// can set the default character encoding to be used here for all character data
// in this segment, otherwise it will default to the system's default encoding
// this.setDefaultEncoding("UTF8");
}
}
Figure 112. A typical IMSFieldMessage subclass
Code to access the fields in InputMessage should look similar to Figure 113.
InputMessage inputMessage = new InputMessage();
messageQueue.getUniqueMessage(inputMessage);
// Return "Field1" as a String using its index
String field1 = inputMessage.getString(1);
// Return "Field2" as a String using its field name (note: int to String conversion)
String field2 = inputMessage.getString("Field2");
Figure 113. Example of how to access the fields in subclass InputMessage
MAX_MESSAGE_LENGTH
public static final short MAX_MESSAGE_LENGTH
The maximum size of the body of a message.
TRANSCODE_VAR_8
public static final int TRANSCODE_VAR_8
The transcode rule for transcode up to 8 bytes long. A blank will be
present between the transcode and the message body if the transcode is
less than 8 bytes.
TRANSCODE_FIXED_9
public static final int TRANSCODE_FIXED_9
The transcode rule for transcode that is exactly 8 bytes long and a blank is
present between the transcode and the message body.
Appendix A. IMS Java package 173

Constructors
TRANSCODE_FIXED_8
public static final int TRANSCODE_FIXED_8
The transcode rule for transcode that is less than 8 bytes and is blank
padded to 8 bytes long.
IMSFieldMessage (DLITypeInfo, int, boolean)
public IMSFieldMessage(DLITypeInfo typeInfo[ ],
int length,
boolean isSPA) throws IllegalArgumentException
Creates a new IMSFieldMessage with the specified message length. The
maximum length can be MAX_MESSAGE_LENGTH (32750) bytes.
Parameters:
174 IMS Version 7 and Java Application Programming
typeInfo - The array of DLITypeInfo objects defining the fields in the
message.
length - Tthe length for the message body of this message.
isSPA - Flag telling whether this message is a SPA message.
Throws: IllegalArgumentException if the length is invalid.
IMSFieldMessage(IMSFieldMessage, DLITypeInfo [ ])
public IMSFieldMessage(IMSFieldMessage message,
DLITypeInfo typeInfo[ ])
Creates a new IMSFieldMessage from an existing IMSFieldMessage. This
allows an application to define one message that contains definitions of
fields common to any input message and use this message to construct
other messages that define the remaining fields.
The following code in Figure 114 demonstrates how this can be used to
define three messages that have the field 'CommandCode' in common.

public class LogicalBaseMessage extends IMSFieldMessage {
final static DLITypeInfo[] typeInfo = {
new DLITypeInfo("CommandCode", DLITypeInfo.CHAR, 1, 20),
}
public LogicalBaseMessage() {
super(typeInfo, 30, false);
}
}
public class LogicalSublcassA extends IMSFieldMessage {
final static DLITypeInfo[] typeInfo = {
new DLITypeInfo("CommandCode", DLITypeInfo.CHAR, 1, 20),
new DLITypeInfo("SomeFieldA", DLITypeInfo.CHAR, 21, 10),
}
public LogicalSubclassA(IMSFieldMessage message) {
super(message, typeInfo);
}
public class LogicalSubclassB extends IMSFieldMessage {
final static DLITypeInfo[] typeInfo = {
new DLITypeInfo("CommandCode", DLITypeInfo.CHAR, 1, 20),
new DLITypeInfo("SomeFieldB", DLITypeInfo.CHAR, 21, 5),
}
public LogicalSubclassB(IMSFieldMessage message) {
super(message, typeInfo);
}
}
Figure 114. Example of coding messages that have the same field in common
Notice a few points about Figure 114.
- The CommandCode field is defined within every class. This is really only
necessary if users of LogicalSubclassA and LogicalSubclassB require
access to this field.
- The length of the "logical" base class, LogicalBaseClass, must be large
enough to contain any of its "logical" subclasses. Therefore,
LogicalBaseClass is 30 bytes long because the fields of
LogicalSubclassA require it.
- Each "logical" subclass must provide a constructor to create itself from
another IMSFieldMessage. Given this approach, an application can
provide message reading logic similar to Figure 115.
Appendix A. IMS Java package 175

Methods
LogicalBaseClass inputMessage = new LogicalBaseClass();
while(messageQueue.getUniqueMessage(inputMessage)) {
String commandCode = inputMessage.getString("CommandCode").trim();
if (commandCode.equals("LogicalSubclassA")) {
processA(new LogicalSubclassA(inputMessage));
}
else if (commandCode.equals("LogicalSubclassB")) {
processB(new LogicalSubclassB(inputMessage));
}
else {
// process an error
}
}
Figure 115. Example of Message reading logic
Parameters:
176 IMS Version 7 and Java Application Programming
message - The IMSFieldMessage, or "logical" base class, that this
message can be created from.
typeInfo - The array of DLITypeInfo objects defining the fields in the
message.
clearBody ()
public void clearBody()
Clears out message body. All other parts of message are left untounched.
clearWarnings ()
public void clearWarnings()
Clears the warning chain for this IMSFieldMessage. After this call
getWarnings returns null until a new warning is reported for this
IMSFieldMessage.
Overrides: clearWarnings in class DLIBaseSegment
getMessageLength ()
public int getMessageLength()
Returns the length of this message. This applies to the message body
only, which excludes the length for the header of the message.
Returns: The length of the message body.

getTransactionID ()
public String getTransactionID()
Return the transaction ID for this input message following reading of the
message by IMSMessageQueue.
Returns: The transactions ID or null if the transaction is not present for
this message.
getWarnings ()
public DLIWarning getWarnings()
Returns the first warning reported by calls on this IMSFieldMessage.
Subsequent warnings will be chained to this DLIWarning. The warning
chain is automatically cleared each time a new message is read from the
queue.
Note
This warning chain only covers warnings caused by IMSFieldMessage
methods.
Returns: The first DLIWarning or null
Overrides: getWarnings in class DLIBaseSegment
setTransCodeRule (int)
public static final void setTransCodeRule(int rule) throws
IllegalArgumentException
Set the Transcode rule for this message. Valid transcode rules are
TRANSCODE_VAR_8, TRANSCODE_FIXED_9, or TRANSCODE_FIXED_8 (default). The
transcode rule is used to determine the length of the transaction code
when parsing the input message. As default, the rule is set to
TRANSCODE_VAR_8, which means that the transcode can be either 8 bytes
long or if less than 8 bytes, there is a blank between the transcode and the
message body in the input message. If the transcode is exactly 8 bytes
long and there is a trailing blank, set the rule to TRANSCODE_FIXED_9. If the
transcode is less than 8 bytes long but is always blank padded to 8 bytes,
set the rule to TRANSCODE_FIXED_8.
Parameters:
rule - The transcode rule for this message
Appendix A. IMS Java package 177

A.5 Class com.ibm.ims.application.IMSMessageQueue
java.lang.Object
+----com.ibm.ims.application.IMSMessageQueue
public final class IMSMessageQueue extends Object
IMSMessageQueue provides services to send and receive messages to an IMS
message queue or to the application's Scratch Pad Area (SPA). The SPA is
used in conversational transactions to store information between one step of
the conversation and the next.
IMSMessageQueue also supports sending messages to another application if an
alternate PCB for that application is specified on the IMSMessageQueue
constructor.
In a non-conversational transaction, it is possible to code the application with
a message loop that retrieves messages until IMS indicates that no more
messages exist on the queue. To support this style of programming,
IMSMessageQueue.getUniqueMessage returns true if a message could be returned
from the queue and false if it could not. The application is required to call
IMSTransaction.commit prior to receiving the second full message.
Figure 116 demonstrates this style of programming.
// Read the first segment of the input message
while(messageQueue.getUniqueMessage(inputMessage1)) {
// Read the second segment of the input message
messageQueue.getNextMessage(inputMessage2);
// Add logic here
// Commit the transaction.
trans.commit();
} // end while
Figure 116. Example of retrieving messages using a while loop
Constructors
IMSMessageQueue ()
public IMSMessageQueue()
Creates a new IMSMessageQueue which sends and receives messages to
and from a terminal.
178 IMS Version 7 and Java Application Programming

Methods
IMSMessageQueue (String)
public IMSMessageQueue(String alternatePCBName)
Creates a new IMSMessageQueue with the alternate PCB Name to send
messages to a different terminal or application program.
Parameters:
alternatePCBName - The alternate PCB Name where the message is
sent.
getAIB ()
public final AIB getAIB()
Returns the Application Interface Block (AIB) used by the message queue.
Returns: AIB The Application Interface Block (AIB).
getNextMessage (IMSFieldMessage)
public boolean getNextMessage(IMSFieldMessage message) throws IMSException
Receives the next segment of the message from IMS. This will receive the
remaining segments for a multisegments message in the program.
Parameters:
message - The IMSFieldMessage object to receive the message.
Returns: True if the message was retrieve, false if no more messages.
Throws: IMSException if a non-blank status code is returned from the
GN call.
getUniqueMessage (IMSFieldMessage)
public boolean getUniqueMessage(IMSFieldMessage message) throws
IMSException
Receives the first segment of an input message from IMS. It is also used
to retrieve the SPA if the program is conversational.
Returns: Flag telling whether a message has been retrieved.
Throws: IMSException if a non-blank status code is returned from the
GU call or if getUniqueMessage is called without commiting the previous
changes.
Appendix A. IMS Java package 179

insertMessage (IMSFieldMessage)
public void insertMessage(IMSFieldMessage message) throws IMSException
Send the output message to IMS. The default formatting will be used.
Parameters:
message - The message to send.
Throws: IMSException if a non-blank status code is returned from the
ISRT call.
insertMessage (IMSFieldMessage, boolean)
public void insertMessage(IMSFieldMessage message,
boolean isLast) throws IMSException
Send the SPA to IMS and end the conversation if isLast is true. This
method should be used in a convesational program only.
Parameters:
message - The message to send.
isLast - Flag telling whether this is the last segment for the
conversation.
Throws: IMSException if a non-blank status code is returned from the
ISRT call.
insertMessage (IMSFieldMessage, String)
public void insertMessage(IMSFieldMessage message,
String modName) throws IMSException
Send the output message to IMS, specifying the Message Output
Descriptor to format the output message.
Parameters:
message - The message to send.
modName - The Message Output Descriptor (MOD) for formatting the
output message.
Throws: IMSException if a non-blank status code is returned from the
ISRT call.
insertMessage (IMSFieldMessage, String, boolean)
public void insertMessage(IMSFieldMessage message,
String modName,
boolean isLast) throws IMSException
180 IMS Version 7 and Java Application Programming

Send the SPA to IMS with the Message Output Descriptor specified and
end the conversation if isLast is true. This method is used in a
convesational program only.
Parameters:
message - The message to send.
modName - The Message Output Descriptor (MOD) for formatting.
isLast - Flag telling whether this is the last segment for the
conversation.
Throws: IMSException if a non-blank status code is returned from the
ISRT call.
setModifiableAlternatePCB (String)
public void setModifiableAlternatePCB(String destination) throws
IMSException
This method should be used to set the destination in the modifiable
alternate PCB. Call this method prior to inserting a message to another
program or logical terminal.
Parameters:
destination - Transaction or logical terminal destination.
A.6 Class com.ibm.ims.application.IMSTransaction
java.lang.Object
+----com.ibm.ims.application.IMSTransaction
public final class IMSTransaction extends Object
The IMSTransaction class provides Java IMS Programs with access to IMS
transaction services such as commit and rollback. The singleton
IMSTransaction object is returned to an application when it calls the static
IMSTransaction method getTransaction. This ensures both that only a single
IMSTransaction object exists for the application and, because the constructor
for IMSTransaction is private, that the class can not be subclassed.
Appendix A. IMS Java package 181

Methods
abend ()
public void abend()
Abnormally terminates the application. It backs out the output messages
sent by the conversational application program.
Parameters:
182 IMS Version 7 and Java Application Programming
exception - The exception that causes the program to abend.
commit ()
public void commit() throws IMSException
Commits the transaction and cleans up the resources. It invokes the JDBC
driver commit method to clean up the JDBC/SQLJ resources.
Throws: IMSException if a non-blank status code is returned from the
system call or if the call to JDBC commit failed.
getTransaction ()
public static IMSTransaction getTransaction()
Returns a new IMSTransaction object.
Returns: An IMSTransaction object.
rollback ()
public void rollback() throws IMSException
Rolls back the transaction and cleans up the resources. It backs out the
messages sent by the application program and invokes the JDBC driver
rollback method to clean up the JDBC/SQLJ resources.
Throws: IMSException if a non-blank status code is returned from the
system call or if the call to JDBC rollback failed.
A.7 Contents of com.ibm.ims.base package
The com.ibm.ims.base package contains the following classes:
com.ibm.ims.base.AIB
com.ibm.ims.base.AlternatePCB
com.ibm.ims.base.DBPCB
com.ibm.ims.base.DLIBaseSegment
com.ibm.ims.base.DLITypeInfo
com.ibm.ims.base.DLITypeInfoList
com.ibm.ims.base.IMSErrorMessages

com.ibm.ims.base.IMSInfo
com.ibm.ims.base.IMSTrace
com.ibm.ims.base.IOPCB
com.ibm.ims.base.JavaToDLI
The com.ibm.ims.base package contains the following exemption classes:
com.ibm.ims.base.DLIJNICallbackException
com.ibm.ims.base.DLIWarning
com.ibm.ims.base.IMSException
A.8 Class com.ibm.ims.base.AIB
java.lang.Object
+----com.ibm.ims.base.AIB
public final class AIB extends Object
The Application Interface Block (AIB) is used by your program to
communicate with IMS. The AIB class contains all the data attributes of the
IMS Application Interface Block and the necessary getter and setter methods.
It contains an IOPCB object, an alternate PCB object, and a DBPCB object. It
also contains a boolean variable indicating if the IOPCB object references an
alternate PCB. See IMS Application Programming: Database Manager.
See also: IOPCB, AlternatePCB, DBPCB .
Constructors
AIB ()
public AIB()
Constructs an AIB. Resource name and I/O area length must be set before
use.
AIB (String, int)
public AIB(String resourceName,
int ioAreaLength)
Constructs an AIB with a resource name and the I/O area length.
Parameters:
resourceName - A PCB name. This parameter should be a maximum
of 8 characters, if greater, will be truncated to 8 characters.
Appendix A. IMS Java package 183

Methods
ioAreaLength - The length of the I/O area.
setAlternatePCB ()
public void setAlternatePCB(boolean isAlternate)
Sets an indicator designating whether the PCB is an alternate PCB.
Parameters:
isAlternate - True if PCB is alternate.
isAlternatePCB ()
public boolean isAlternatePCB()
Returns true if PCB is an alternate PCB.
Returns: True if PCB is alternate or false if PCB is not alternate.
getSubFunctionCode ()
public String getSubFunctionCode()
Returns the subfunction code in this AIB.
Returns: The AIB's subfunction code.
setSubFunctionCode ()
public void setSubFunctionCode(String subFunctionCode)
Sets the subfunction code in this AIB. This parameter should be a
maximum of 8 characters, if greater, will be truncated to 8 characters.
Parameters:
184 IMS Version 7 and Java Application Programming
subFunctionCode - The AIB's subfunction code.
getResourceName ()
public String getResourceName()
Returns the resource name (PCB name) in this AIB.
Returns: The AIB's resource name.
setResourceName ()
public void setResourceName(String resourceName)
Sets the resource name (usually PCB name) in this AIB. This parameter
should be a maximum of 8 characters, if greater, will be truncated to 8
characters.

Parameters:
resourceName - The AIB's resource name.
getOALength ()
public int getOALength()
Returns the maximum output area length in this AIB.
Returns: The output area length used.
setOALength ()
public void setOALength(int length)
Sets the maximum output area length in this AIB.
Parameters:
length - The output area length used.
getOAUse ()
public int getOAUse()
Returns the output area length used in this AIB.
Returns: The output area length used.
getReturnCode ()
public int getReturnCode()
Returns the return code produced by the last DLI call through this AIB.
Returns: The return code of the last DLI call.
getReasonCode ()
public int getReasonCode()
Returns the reason code produced by the last DLI call through this AIB.
Returns: The reason code of the last DLI call.
getErrorCodeExtension ()
public int getErrorCodeExtension()
Returns the error code extension produced by the last DLI call through this
AIB.
Returns: The error code extension of the last DLI call.
getDBPCB ()
public DBPCB getDBPCB()
Appendix A. IMS Java package 185

Returns the DBPCB object in this AIB.
Returns: The DBPCB in this AIB.
getIOPCB ()
public IOPCB getIOPCB()
Returns the IOPCB object in this AIB.
Returns: The IOPCB in this AIB.
getAlternatePCB ()
public AlternatePCB getAlternatePCB()
Returns the Alternate PCB object in this AIB.
Returns: The Alternate PCB in this AIB.
A.9 Class com.ibm.ims.base.AlternatePCB
Methods
java.lang.Object
+----com.ibm.ims.base.AlternatePCB
public final class AlternatePCB extends Object
The AlternatePCB class contains all the data attributes of the IMS Alternate
Program Communication Block and the necessary getter and setter methods.
Use alternate PCB to send output messages to terminal other than the
originating terminal or to send messages to other application programs.
Alternate PCBs can be found for a particular terminal or program, or they can
be defined as modifiable. If the alternate PCB is modifiable, set the
destination using the CHNG (Change) call. For further information, see the
manual, IMS Application Programming: Transaction Manager.
getMessageDestination ()
public String getMessageDestination()
Returns the logical terminal name in this Alternate PCB.
Returns: The Alternate PCB's logical terminal name.
getStatusCode ()
public short getStatusCode()
186 IMS Version 7 and Java Application Programming

Returns the status code from the last DLI call using this Alternate PCB.
See IMS V7 Messages and Codes, GC26-9433-00 for information about
IMS status codes.
Returns: The Alternate PCB's IMS status code.
A.10 Class com.ibm.ims.base.DBPCB
Methods
java.lang.Object
+----com.ibm.ims.base.DBPCB
public final class DBPCB extends Object
The DBPCB class contains all the data attributes of the IMS Database Program
Communication Block and the necessary getter and setter methods. IMS
describes the results of the calls your program issues in the DB PCB that is
referenced in the call. For more information, see IMS Application
Programming: Database Manager, SC26-9422-00.
getDBName ()
public String getDBName()
Returns the database name in this DBPCB. The maximum length of this
field is 8 characters.
Returns: The DBPCB's database name.
getStatusCode ()
public short getStatusCode()
Returns the IMS status code of the last DLI call using this DBPCB.
Returns: The DBPCB's IMS status code.
getProcessOptions ()
public String getProcessOptions()
Returns the IMS processing options in this DBPCB.
Returns: The DBPCB's IMS processing options.
getSegmentName ()
public String getSegmentName()
Appendix A. IMS Java package 187

Returns the IMS segment name in this DBPCB from the last DLI call using
this DBPCB.
Returns: The DBPCB's segment name.
getKeyFeedback ()
public byte[ ] getKeyFeedback()
Returns the concatenated key in this DBPCB from the last DLI call using
this DBPCB. Returns null if no concatenated key returned from IMS.
Returns: The DBPCB's concatenated key.
getSegmentLevelNumber ()
public int getSegmentLevelNumber()
Returns the segment level in this DBPCB from the last DLI call using this
DBPCB.
Returns: The DBPCB's segment level.
getKeyFeedbackLength ()
public int getKeyFeedbackLength()
Returns the concatenated key length in this DBPCB from the last DLI call
using this DBPCB.
Returns: The DBPCB's concatenated key length.
getNumberSensitiveSegments ()
public int getNumberSensitiveSegments()
Returns the number of sensitive segments in this DBPCB from the last DLI
call using this DBPCB.
Returns: The DBPCB's number of sensitive segments.
getRSA ()
public byte[ ] getRSA()
Returns the record search argument (RSA) from GSAM DB PCB. It is 8
bytes long or null if DB PCB is not GSAM. NOTE: if GSAM, the
keyFeedback is 12 bytes long. The first 8 bytes is record search argument
which can be used later on if you want to retrieve that record directly by
including it as one of the parameters on a GU call. The last 4 bytes is the
length of the undefined-length record(RECFM=U).
Returns: GSAM DB PCB record search argument (RSA).
188 IMS Version 7 and Java Application Programming

getUndefinedLengthRecordLength ()
public int getUndefinedLengthRecordLength()
Returns the length of the undefined-length record after GSAM GU or GN
call. Return 0 if DB PCB is not GSAM.
Returns: The length of the undefined-length record.
A.11 Class com.ibm.ims.base.DLIBaseSegment
Variables
Constructors
Methods
java.lang.Object
+----com.ibm.ims.base.DLIBaseSegment
public abstract class DLIBaseSegment extends Object Implements Cloneable.
IoArea
protected byte ioArea[]
ioAreaOffset
protected int ioAreaOffset
ioAreaLength
protected int ioAreaLength
DLIBaseSegment (String, DLITypeInfo, int)
protected DLIBaseSegment(String segmentName,
DLITypeInfo typeInfo[],
int length)
clearWarnings ()
protected void clearWarnings()
clone ()
public Object clone()
Creates a new object of the same class as this object. This method does
not copy the type information so that all instances share the same field
definitions.
Appendix A. IMS Java package 189

Returns: java.lang.Object.
Overrides: clone in class Object.
getBigDecimal (int)
public BigDecimal getBigDecimal(int index) throws DLIException
Returns the field indicated by the index as a BigDecimal. The index
parameter is the index of the desired field that was passed to the
constructor in the DLITypeInfo array. The index is one based.
For example, if the fields in the segment were added to the DLITypeInfo
array in order, then the first field in the segment would be index 1, the
second index 2, and so on.
Parameters:
index - The one-based index of the desired field in the DLITypeInfo
array.
Returns: The value of the field as a BigDecimal.
Throws: DLIException if the conversion cannot be done.
getBigDecimal (int, int)
public BigDecimal getBigDecimal(int index,
int scale) throws DLIException
Returns the field indicated by the index as a BigDecimal. The index
parameter is the index of the desired field that was passed to the
constructor in the DLITypeInfo array. The index is one based. For
example, if the fields in the segment were added to the DLITypeInfo
array in order, then the first field in the segment would be index 1, the
second index 2, and so on.
Parameters:
190 IMS Version 7 and Java Application Programming
index - The one-based index of the desired field in the DLITypeInfo
array.
scale - The number of digits to the right of the decimal.
Returns: The value of the field as a BigDecimal.
Throws: DLIException if the conversion cannot be done.

getBigDecimal (String)
public BigDecimal getBigDecimal(String fieldName) throws DLIException
Returns the field specified by the parameter as a BigDecimal. The
fieldName parameter is the name of the field as it was registered in the
DLITypeInfo array.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
Returns: The value of the field as a BigDecimal.
Throws: DLIException if the field name is not found in the segment.
getBigDecimal (String, int)
public BigDecimal getBigDecimal(String fieldName,
int scale) throws DLIException
Returns the field specified by the parameter as a BigDecimal. The
fieldName parameter is the name of the field as it was registered in the
DLITypeInfo array.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
scale - The number of digits to the right of the decimal.
Returns: The value of the field as a BigDecimal.
Throws: DLIException if the field name is not found in the segment.
getBoolean (int)
public boolean getBoolean(int index) throws DLIException
Returns the field indicated by the index as a boolean. The index parameter
is the index of the desired field that was passed to the constructor in the
DLITypeInfo array. The index is one based. For example, if the fields in the
segment were added to the DLITypeInfo array in order, then the first field in
the segment would be index 1, the second index 2, and so on.
Parameters:
index - The 1-based index of the desired field in the DLITypeInfo
array.
Returns: The value of the field as a boolean.
Throws: DLIException if the conversion cannot be done.
Appendix A. IMS Java package 191

getBoolean (String)
public boolean getBoolean(String fieldName) throws DLIException
Returns the field specified by the parameter as a boolean. The fieldName
parameter is the name of the field as it was registered in the DLITypeInfo
array.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
Returns: The value of the field as a boolean.
Throws: DLIException if the field name is not found in the segment.
getByte (int)
public byte getByte(int index) throws DLIException
Returns the field indicated by the index as a byte. The index parameter is
the index of the desired field that was passed to the constructor in the
DLITypeInfo array. The index is one based. For example, if the fields in the
segment were added to the DLITypeInfo array in order, then the first field in
the segment would be index 1, the second index 2, and so on.
Parameters:
index - The one-based index of the desired field in the DLITypeInfo
array.
Returns: The value of the field as a byte.
Throws: DLIException if the conversion cannot be done.
getByte (String)
public byte getByte(String fieldName) throws DLIException
Returns the field specified by the parameter as a byte. The fieldName
parameter is the name of the field as it was registered in the DLITypeInfo
array.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
Returns: The value of the field as a byte.
Throws: DLIException if the field name is not found in the segment.
192 IMS Version 7 and Java Application Programming

getBytes (int)
public byte[ ] getBytes(int index) throws DLIException
Returns the field indicated by the index "as is" (ie; the raw bytes of the
field). The index parameter is the index of the desired field that was
passed to the constructor in the DLITypeInfo array. The index is one based.
For example, if the fields in the segment were added to the DLITypeInfo
array in order, then the first field in the segment would be index 1, the
second index 2, and so on.
Parameters:
index - The 1-based index of the desired field in the DLITypeInfo
array.
Returns: The raw bytes of the field as an array of bytes.
Throws: DLIException if the conversion cannot be done.
getBytes (String)
public byte[] getBytes(String fieldName) throws DLIException
Returns the field specified by the parameter "as is" (ie; the raw bytes of
the field). The fieldName parameter is the name of the field as it was
registered in the DLITypeInfo array.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
Returns: The raw bytes of the field as a byte array.
Throws: DLIException if the field name is not found in the segment.
getDate (int)
public Date getDate(int index) throws DLIException
Returns the field indicated by the index as a java.sql.Date object. The
index parameter is the index of the desired field that was passed to the
constructor in the DLITypeInfo array. The index is one based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 1, the second index 2,
and so on.
Parameters:
index - The 1-based index of desired field in the DLITypeInfo array.
Returns: The value of the field as a java.sql.Date object.
Throws: DLIException if the conversion cannot be done.
Appendix A. IMS Java package 193

getDate (String)
public Date getDate(String fieldName) throws DLIException
Returns the field specified by the parameter as a java.sql.Date object. The
fieldName parameter is the name of the field as it was registered in the
DLITypeInfo array.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
Returns: The value of the field as a java.sql.Date object.
Throws: DLIException if the field name is not found in the segment.
getDefaultEncoding ()
public String getDefaultEncoding()
Returns the default character encoding for this segment.
Returns: java.lang.String.
getDouble (int)
public double getDouble(int index) throws DLIException
Returns the field indicated by the index as a double. The index parameter
is the index of the desired field that was passed to the constructor in the
DLITypeInfo array. The index is one based.
For example, if the fields in the segment were added to the DLITypeInfo
array in order, then the first field in the segment would be index 1, the
second index 2, and so on.
Parameters:
index - The 1-based index of the desired field in the DLITypeInfo
array.
Returns: The value of the field as a double.
Throws: DLIException if the conversion cannot be done.
getDouble (String)
public double getDouble(String fieldName) throws DLIException
Returns the field specified by the parameter as a double. The fieldName
parameter is the name of the field as it was registered in the DLITypeInfo
array.
194 IMS Version 7 and Java Application Programming

Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
Returns: The value of the field as a double.
Throws: DLIException if the field name is not found in the segment.
getFloat (int)
public float getFloat(int index) throws DLIException
Returns the field indicated by the index as a float. The index parameter is
the index of the desired field that was passed to the constructor in the
DLITypeInfo array. The index is one based.
For example, if the fields in the segment were added to the DLITypeInfo
array in order, then the first field in the segment would be index 1, the
second index 2, and so on.
Parameters:
index - The 1-based index of the desired field in the DLITypeInfo
array.
Returns: The value of the field as a float.
Throws: DLIException if the conversion cannot be done.
getFloat (String)
public float getFloat(String fieldName) throws DLIException
Returns the field specified by the parameter as a float. The fieldName
parameter is the name of the field as it was registered in the DLITypeInfo
array.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
Returns: The value of the field as a float.
Throws: DLIException if the field name is not found in the segment.
getInt (int)
public int getInt(int index) throws DLIException
Returns the field indicated by the index as an int. The index parameter is
the index of the desired field that was passed to the constructor in the
DLITypeInfo array. The index is one based. For example, if the fields in the
Appendix A. IMS Java package 195

segment were added to the DLITypeInfo array in order, then the first field in
the segment would be index 1, the second index 2, and so on.
Parameters:
index - The 1-based index of the desired field in the DLITypeInfo
array.
Returns: The value of the field as an int.
Throws: DLIException if the conversion cannot be done.
getInt (String)
public int getInt(String fieldName) throws DLIException
Returns the field specified by the parameter as an int. The fieldName
parameter is the name of the field as it was registered in the DLITypeInfo
array.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
Returns: The value of the field as an int.
Throws: DLIException if the field name is not found in the segment.
getLong (int)
public long getLong(int index) throws DLIException
Returns the field indicated by the index as a long. The index parameter is
the index of the desired field that was passed to the constructor in the
DLITypeInfo array. The index is one based. For example, if the fields in the
segment were added to the DLITypeInfo array in order, then the first field in
the segment would be index 1, the second index 2, and so on.
Parameters:
index - The 1-based index of the desired field in the DLITypeInfo
array.
Returns: The value of the field as a long.
Throws: DLIException if the conversion cannot be done.
getLong (String)
public long getLong(String fieldName) throws DLIException
Returns the field specified by the parameter as a long. The fieldName
parameter is the name of the field as it was registered in the DLITypeInfo
array.
196 IMS Version 7 and Java Application Programming

Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
Returns: The value of the field as a long.
Throws: DLIException if the field name is not found in the segment.
getSegmentName ()
public String getSegmentName()
Returns the name of the segment as stored in the database.
Returns: java.lang.String.
getShort (int)
public short getShort(int index) throws DLIException
Returns the field indicated by the index as a short. The index parameter is
the index of the desired field that was passed to the constructor in the
DLITypeInfo array. The index is one based. For example, if the fields in the
segment were added to the DLITypeInfo array in order, then the first field in
the segment would be index 1, the second index 2, and so on.
Parameters:
index - The 1-based index of the desired field in the DLITypeInfo
array.
Returns: The value of the field as a short.
Throws: DLIException if the conversion cannot be done.
getShort (String)
public short getShort(String fieldName) throws DLIException
Returns the field specified by the parameter as a short. The fieldName
parameter is the name of the field as it was registered in the DLITypeInfo
array.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
Returns: The value of the field as a short.
Throws: DLIException if the field name is not found in the segment.
Appendix A. IMS Java package 197

getString (int)
public String getString(int index) throws DLIException
Returns the field indicated by the index as a String. The index parameter
is the index of the desired field that was passed to the constructor in the
DLITypeInfo array. The index is one based. For example, if the fields in the
segment were added to the DLITypeInfo array in order, then the first field in
the segment would be index 1, the second index 2, and so on.
Parameters:
index - The 1-based index of the desired field in the DLITypeInfo
array.
Returns: The value of the field as a String.
Throws: DLIException if the conversion cannot be done.
getString (String)
public String getString(String fieldName) throws DLIException
Returns the field specified by the parameter as a String. The fieldName
parameter is the name of the field as it was registered in the DLITypeInfo
array.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
Returns: The value of the field as a String.
Throws: DLIException if the field name is not found in the segment.
getTime (int)
public Time getTime(int index) throws DLIException
Returns the field indicated by the index as a java.sql.Time object. The
index parameter is the index of the desired field that was passed to the
constructor in the DLITypeInfo array. The index is one based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 1, the second index 2,
and so on.
Parameters:
index - The 1-based index of the desired field in the DLITypeInfo
array.
Returns: The value of the field as a java.sql.Time object.
Throws: DLIException if the conversion cannot be done.
198 IMS Version 7 and Java Application Programming

getTime (String)
public Time getTime(String fieldName) throws DLIException
Returns the field specified by the parameter as a java.sql.Time object. The
fieldName parameter is the name of the field as it was registered in the
DLITypeInfo array.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
Returns: The value of the field as a java.sql.Time object.
Throws: DLIException if the field name is not found in the segment.
getTimestamp (int)
public Timestamp getTimestamp(int index) throws DLIException
Returns the field indicated by the index as a java.sql.Timestamp object.
The index parameter is the index of the desired field that was passed to
the constructor in the DLITypeInfo array. The index is one based. For
example, if the fields in the segment were added to the DLITypeInfo array
in order, then the first field in the segment would be index 1, the second
index 2, and so on.
Parameters:
index - The 1-based index of desired field in the DLITypeInfo array.
Returns: The value of the field as a java.sql.Timestamp object.
Throws: DLIException if the conversion cannot be done.
getTimestamp (String)
public Timestamp getTimestamp(String fieldName) throws DLIException
Returns the field specified by the parameter as a java.sql.Timestamp
object. The fieldName parameter is the name of the field as it was
registered in the DLITypeInfo array.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
Returns: The value of the field as a java.sql.Timestamp object.
Throws: DLIException if the field name is not found in the segment.
getTypeInfo ()
public DLITypeInfo[] getTypeInfo()
Appendix A. IMS Java package 199

Returns an array of the DLITypeInfo instances for this segment.
Returns: The DLITypeInfo array.
getTypeInfo (int)
public DLITypeInfo getTypeInfo(int index)
Returns the DLITypeInfo of the field specified by the index parameter.
Parameters:
index - The 1-based index of the desired field.
Returns: The DLITypeInfo of the specified field.
getTypeInfo (String)
public DLITypeInfo getTypeInfo(String fieldName) throws DLIException
Returns the DLITypeInfo of the field specified by the fieldName parameter.
The fieldName parameter is the name given to the field when it was
registered with this class's constructor.
Parameters:
index - The zero-based index of the desired field.
Returns: The DLITypeInfo of the specified field.
Throws: DLIException if the field does not exist.
getWarnings ()
protected DLIWarning getWarnings()
Returns: java.sql.SQLWarning.
setBigDecimal (int, BigDecimal)
public void setBigDecimal(int index,
BigDecimal value) throws DLIException
Sets the field indicated by the index to the specified BigDecimal value. The
index parameter is the index of the desired field that was passed to the
constructor in the DLITypeInfo array. The index is one based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 1, the second index 2,
and so on.
Parameters:
200 IMS Version 7 and Java Application Programming
index - The 1-based index of the desired field in the DLITypeInfo
array.
value - The new value for the field.

Throws: DLIException if there is a conversion failure.
setBigDecimal (String,BigDecimal)
public void setBigDecimal(String fieldName,
BigDecimal value) throws DLIException
Sets the field indicated by the fieldName parameter to the specified
BigDecimal value. The fieldName parameter is the name of the field as it
was registered in the DLITypeInfo array. The index is zero based. For
example, if the fields in the segment were added to the DLITypeInfo array
in order, then the first field in the segment would be index 0, the second
index 1, and so on.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
value - The new value for the field.
Throws: DLIException if the field name is not found in the segment or if
there is a conversion failure.
setBoolean (int,boolean)
public void setBoolean(int index,
boolean value) throws DLIException
Sets the field indicated by the index to the specified boolean value. The
index parameter is the index of the desired field that was passed to the
constructor in the DLITypeInfo array. The index is one based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 1, the second index 2,
and so on.
Parameters:
index - The 1-based index of the desired field in the DLITypeInfo
array.
value - The new value for the field.
Throws: DLIException if there is a conversion failure.
setBoolean (String,boolean)
public void setBoolean(String fieldName,
boolean value) throws DLIException
Sets the field indicated by the fieldName parameter to the specified boolean
value. The fieldName parameter is the name of the field as it was
registered in the DLITypeInfo array. The index is zero based. For example,
Appendix A. IMS Java package 201

if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 0, the second index 1,
and so on.
Parameters:
202 IMS Version 7 and Java Application Programming
fieldName - The name of the field as registered in the DLITypeInfo
array.
value - The new value for the field.
Throws: DLIException if the field name is not found in the segment or if
there is a conversion failure.
setByte (int,byte)
public void setByte(int index,
byte value) throws DLIException
Sets the field indicated by the index to the specified byte value. The index
parameter is the index of the desired field that was passed to the
constructor in the DLITypeInfo array. The index is one based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 1, the second index 2,
and so on.
Parameters:
index - The 1-based index of the desired field in the DLITypeInfo
array.
value - The new value for the field.
Throws: DLIException if there is a conversion failure.
setByte (String,byte)
public void setByte(String fieldName,
byte value) throws DLIException
Sets the field indicated by the fieldName parameter to the specified byte
value. The fieldName parameter is the name of the field as it was
registered in the DLITypeInfo array. The index is zero based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 0, the second index 1,
and so on.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
value - The new value for the field.

Throws: DLIException if the field name is not found in the segment or if
there is a conversion failure.
setBytes (int, byte)
public void setBytes(int index,
byte value[]) throws DLIException
Sets the field indicated by the index to the exact bytes passed in the array,
with no conversion. The index parameter is the index of the desired field
that was passed to the constructor in the DLITypeInfo array. The index is
one based. For example, if the fields in the segment were added to the
DLITypeInfo array in order, then the first field in the segment would be
index 1, the second index 2, and so on.
Parameters:
index - The 1-based index of the desired field in the DLITypeInfo
array.
value - The new value for the field.
Throws: NumberFormatException if the length of the byte array is not
equal to the length of the field as defined in the DLITypeInfo.
setBytes (String, byte)
public void setBytes(String fieldName,
byte value[]) throws DLIException
Sets the field indicated by the fieldName parameter to the exact bytes
passed in the array, with no conversion. The fieldName parameter is the
name of the field as it was registered in the DLITypeInfo array. The index is
zero based. For example, if the fields in the segment were added to the
DLITypeInfo array in order, then the first field in the segment would be
index 0, the second index 1, and so on.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
value - The new value for the field.
Throws:
NumberFormatException if the length of the byte array is not equal to
the length of the field as defined in the DLITypeInfo.
DLIException if the field name is not found in the segment.
setDate (int, Date)
public void setDate(int index,
Date value) throws DLIException
Appendix A. IMS Java package 203

Sets the field indicated by the index to the specified Date value. The index
parameter is the index of the desired field that was passed to the
constructor in the DLITypeInfo array. The index is one based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 1, the second index 2,
and so on.
Parameters:
index - The 1-based index of the desired field in the DLITypeInfo
array.
value - The new value for the field.
Throws: DLIException if the encoding scheme for the Date when it is
formatted to a String is not supported or if there is a conversion failure.
setDate (String, Date)
public void setDate(String fieldName,
Date value) throws DLIException
Sets the field indicated by the fieldName parameter to the specified Date
value. The fieldName parameter is the name of the field as it was
registered in the DLITypeInfo array. The index is zero based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 0, the second index 1,
and so on.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
value - The new value for the field.
Throws: DLIException if the encoding scheme for the Date when it is
formatted to a String is not supported, if the field name is not found in
the segment, or if there is a conversion failure.
setDefaultEncoding (String)
public void setDefaultEncoding(String encoding)
Sets the character encoding that all character data in the segment
adheres to. This encoding can also be overridden on a per field basis.
Parameters:
encoding - The character encoding.
See Also: DLITypeInfo.
204 IMS Version 7 and Java Application Programming

setDouble (int, double)
public void setDouble(int index,
double value) throws DLIException
Sets the field indicated by the index to the specified double value. The
index parameter is the index of the desired field that was passed to the
constructor in the DLITypeInfo array. The index is one based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 1, the second index 2,
and so on.
Parameters:
index - The 1-based index of the desired field in the DLITypeInfo
array.
value - The new value for the field.
Throws: DLIException if there is a conversion failure.
setDouble (String, double)
public void setDouble(String fieldName,
double value) throws DLIException
Sets the field indicated by the fieldName parameter to the specified double
value. The fieldName parameter is the name of the field as it was
registered in the DLITypeInfo array. The index is zero based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 0, the second index 1,
and so on.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
value - The new value for the field.
Throws: DLIException if the field name is not found in the segment or
there is a conversion failure.
setFloat (int, float)
public void setFloat(int index,
float value) throws DLIException
Sets the field indicated by the index to the specified float value. The index
parameter is the index of the desired field that was passed to the
constructor in the DLITypeInfo array. The index is one based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 1, the second index 2,
and so on.
Appendix A. IMS Java package 205

Parameters:
index - The 1-based index of the desired field in the DLITypeInfo
array.
value - The new value for the field.
Throws: DLIException if there is a conversion failure.
setFloat (String, float)
public void setFloat(String fieldName,
float value) throws DLIException
Sets the field indicated by the index to the specified float value. The index
parameter is the index of the desired field that was passed to the
constructor in the DLITypeInfo array. The index is one based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 1, the second index 2,
and so on.
Parameters:
index - The 1-based index of the desired field in the DLITypeInfo
array.
value - The new value for the field.
Throws: DLIException if the field name is not found in the segment or
there is a conversion failure.
setInt (int, int)
public void setInt(int index,
int value) throws DLIException
Sets the field indicated by the index to the specified int value. The index
parameter is the index of the desired field that was passed to the constructor
in the DLITypeInfo array. The index is one based. For example, if the fields in
the segment were added to the DLITypeInfo array in order, then the first field
in the segment would be index 1, the second index 2, and so on.
Parameters:
index - The 1-based index of the desired field in the DLITypeInfo
array.
value - The new value for the field.
Throws: DLIException if there is a conversion failure.
setInt (String, int)
public void setInt(String fieldName,
int value) throws DLIException
206 IMS Version 7 and Java Application Programming

Sets the field indicated by the fieldName parameter to the specified int
value. The fieldName parameter is the name of the field as it was
registered in the DLITypeInfo array. The index is zero based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 0, the second index 1,
and so on.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
value - The new value for the field.
Throws: DLIException if the field name is not found in the segment or if
there is a conversion failure.
setLong (int, long)
public void setLong(int index,
long value) throws DLIException
Sets the field indicated by the index to the specified long value. The index
parameter is the index of the desired field that was passed to the
constructor in the DLITypeInfo array. The index is one based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 1, the second index 2,
and so on.
Parameters:
index - The 1-based index of the desired field in the DLITypeInfo
array.
value - The new value for the field.
Throws: DLIException if there is a conversion failure.
setLong (String, long)
public void setLong(String fieldName, long value) throws DLIException
Sets the field indicated by the fieldName parameter to the specified long
value. The fieldName parameter is the name of the field as it was
registered in the DLITypeInfo array. The index is zero based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 0, the second index 1,
and so on.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
Appendix A. IMS Java package 207

value - The new value for the field.
Throws: DLIException if the field name is not found in the segment or if
there is a conversion failure.
setShort (int, short)
public void setShort(int index,
short value) throws DLIException
Sets the field indicated by the index to the specified short value. The
index parameter is the index of the desired field that was passed to the
constructor in the DLITypeInfo array. The index is one based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 1, the second index 2,
and so on.
Parameters:
index - The 1-based index of the desired field in the DLITypeInfo
array.
value - The new value for the field.
Throws: DLIException if there is a conversion failure.
setShort (String, short)
public void setShort(String fieldName,
short value) throws DLIException
Sets the field indicated by the fieldName parameter to the specified short
value. The fieldName parameter is the name of the field as it was
registered in the DLITypeInfo array. The index is zero based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 0, the second index 1,
and so on.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
value - The new value for the field.
Throws: DLIException if the field name is not found in the segment or if
there is a conversion failure.
setString (int,String)
public void setString(int index,
String value) throws DLIException
208 IMS Version 7 and Java Application Programming

Sets the field indicated by the index to the specified String value. The
index parameter is the index of the desired field that was passed to the
constructor in the DLITypeInfo array. The index is one based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 1, the second index 2,
and so on.
Parameters:
index - The 1-based index of the desired field in the DLITypeInfo
array.
value - The new value for the field.
Throws: DLIException if the encoding scheme is not supported or if
there is a conversion failure.
setString (String, String)
public void setString(String fieldName,
String value) throws DLIException
Sets the field indicated by the fieldName parameter to the specified String
value. The fieldName parameter is the name of the field as it was
registered in the DLITypeInfo array. The index is zero based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 0, the second index 1,
and so on.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
value - The new value for the field.
Throws: DLIException if the field name is not found in the segment, if
the encoding scheme is not supported, or if there is a conversion
failure.
setTime (int, Time)
public void setTime(int index,
Time value) throws DLIException
Sets the field indicated by the index to the specified Time value. The index
parameter is the index of the desired field that was passed to the
constructor in the DLITypeInfo array. The index is one based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 1, the second index 2,
and so on.
Parameters:
Appendix A. IMS Java package 209

index - The 1-based index of the desired field in the DLITypeInfo
array.
value - The new value for the field.
Throws: DLIException if the encoding scheme for the Time when it is
formatted to a String is not supported or if there is a conversion failure.
setTime (String, Time)
public void setTime(String fieldName,
Time value) throws DLIException
Sets the field indicated by the fieldName parameter to the specified Time
value. The fieldName parameter is the name of the field as it was
registered in the DLITypeInfo array. The index is zero based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 0, the second index 1,
and so on.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
value - The new value for the field.
Throws: DLIException if the encoding scheme for the Time when it is
formatted to a String is not supported, if the field name is not found in
the segment, or if there is a conversion failure.
setTimestamp (int, Timestamp)
public void setTimestamp(int index,
Timestamp value) throws DLIException
Sets the field indicated by the index to the specified Timestamp value. The
index parameter is the index of the desired field that was passed to the
constructor in the DLITypeInfo array. The index is one based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 1, the second index 2,
and so on.
Parameters:
210 IMS Version 7 and Java Application Programming
index - The 1-based index of the desired field in the DLITypeInfo
array.
value - The new value for the field.
Throws: DLIException if the encoding scheme for the Timestamp when it
is formatted to a String is not supported or if there is a conversion
failure.

setTimestamp (String, Timestamp)
public void setTimestamp(String fieldName,
Timestamp value) throws DLIException
Sets the field indicated by the fieldName parameter to the specified
Timestamp value. The fieldName parameter is the name of the field as it was
registered in the DLITypeInfo array. The index is zero based. For example,
if the fields in the segment were added to the DLITypeInfo array in order,
then the first field in the segment would be index 0, the second index 1,
and so on.
Parameters:
fieldName - The name of the field as registered in the DLITypeInfo
array.
value - The new value for the field.
Throws: DLIException if the encoding scheme for the Timestamp when it
is formatted to a String is not supported, if the field name is not found in
the segment, or if there is a conversion failure.
A.12 Class com.ibm.ims.base.DLITypeInfo
java.lang.Object
+----com.ibm.ims.base.DLITypeInfo
public class DLITypeInfo extends Object
A DLITypeInfo object is used to provide the layout of a segment's fields to the
base class DLISegment. With this metadata, the DLISegment class is able to
provide access to all of the fields in any segment using either the defined field
name or the 1-based index of the DLITypeInfo object in the array that is
registered for each segment type. The defined field name can be an alias for
the defined search field name in the DBD source file. When referring to the
field,you can use the field alias instead of the search or key field name, as
these field names are limited to only 8 characters. Note that the field names
are case sensitive and must be written exactly as defined in the DLITypeInfo
objects. When defining a key or search field, you must use the
DLITypeInfo(String, int, int, int, String) constructor, which allows you to
provide the alias and actual name of the search or key field.
Appendix A. IMS Java package 211

Variables
TINYINT
public static final int TINYINT
INTEGER
public static final int INTEGER
CHAR
public static final int CHAR
DOUBLE
public static final int DOUBLE
FLOAT
public static final int FLOAT
BIT
public static final int BIT
BLOB
public static final int BLOB
BIGINT
public static final int BIGINT
SMALLINT
public static final int SMALLINT
VARCHAR
public static final int VARCHAR
PACKEDDECIMAL
public static final int PACKEDDECIMAL
ZONEDDECIMAL
public static final int ZONEDDECIMAL
DATE
public static final int DATE
TIME
public static final int TIME
212 IMS Version 7 and Java Application Programming

Constructors
TIMESTAMP
public static final int TIMESTAMP
TYPELIST
public static final int TYPELIST
BINARY
public static final int BINARY
DLITypeInfo (String, int, int, int)
public DLITypeInfo(String fieldName,
int type,
int startingOffset,
int length)
Constructs a DLITypeInfo object. This constructor is only to be used with
non-key and non-search fields. It cannot be used for zoned decmial, packed
decimal, date, time, and timestamp fields. Use the DLITypeInfo(String,
String, int, int, int) or DLITypeInfo(String, String, int, int, int, String)
constructors for these types. The DLITypeInfo class defines several constants
that can be supplied as values for the type argument: CHAR, INTEGER, DOUBLE,
FLOAT, BIT, BLOB, BIGINT, TINYINT, BINARY, and SMALLINT. Certain types have
predefined lengths and cannot be changed. The INTEGER and FLOAT types are
always 4 bytes long. The DOUBLE and BIGINT types are always 8 bytes long.
The SMALLINT type is always 2 bytes long. The TINYINT and BIT types are
always 1 byte long. If another length value is specified for one of these types,
an exception will be thrown.
Parameters:
fieldName - The name of the field.
type - The type of the field.
startingOffset - The starting offset in the I/O area of this field,
beginning at offset 1.
length - The length, in bytes, of this field.
Throws: IllegalArgumentException if the starting offset is less than zero,
an unsupported type is given, or an invalid length is given.
See Also: DLISegment.
Appendix A. IMS Java package 213

DLITypeInfo (String, int, int, int, String)
public DLITypeInfo(String fieldName,
int type,
int startingOffset,
int length,
String searchFieldName)
Constructs a DLITypeInfo object. This constructor is to be used with all key
and search fields. It cannot be used for zoned decmial, packed decimal, date,
time, and timestamp fields. Use the DLITypeInfo(String, String, int, int,
int) or DLITypeInfo(String, String, int, int, int, String) constructors for
these types. It provides functionality to provide an alias for the key and
search fields. This alias name is not limited to 8 characters. The DLITypeInfo
class defines several constants that can be supplied as values for the type
argument: CHAR, INTEGER, DOUBLE, FLOAT, BIT, BLOB, BIGINT, TINYINT, BINARY, and
SMALLINT. Certain types have predefined lengths and cannot be changed. The
INTEGER and FLOAT types are always 4 bytes long. The DOUBLE and BIGINT types
are always 8 bytes long. The SMALLINT type is always 2 bytes long. The
TINYINT and BIT types are always 1 byte long. If another length value is
specified for one of these types, an exception will be thrown.
Parameters:
fieldName - The name of the field. This name can be an alias that
maps to the the actual name as defined in the DBD source file,
which is given by the searchFieldName parameter.
type - The type of the field.
startingOffset - The starting offset in the I/O area of this field,
beginning at offset 1.
length - The length, in bytes, of this field.
searchFieldName - The name of the search or key field exactly as
defined in the DBD source file.
Throws: IllegalArgumentException if the starting offset is less than zero,
an unsupported type is given, or an invalid length is given.
See Also: DLISegment.
DLITypeInfo (String, String, int, int)
public DLITypeInfo(String fieldName,
String typeQualifier,
int type,
int startingOffset,int length)
Constructs a DLITypeInfo object. This constructor is to be used with non-key
and non-search fields of zoned or packed decimal and Date/Time/Timestamp
214 IMS Version 7 and Java Application Programming

data. Use the DLITypeInfo(String, String, int, int, int) or
DLITypeInfo(String, String, int, int, int, String) constructors for all other
types.
The uses of the type qualifier are as follows: If the field type is either packed
or zoned decimal, the type qualifier is the PICTURE string representing the
layout of the field. All COBOL PICTURE strings containing valid combinations
of 9s. Ps, Vs, and Ss are supported. For zoned decimal numbers, the decimal
point (.) can also be used in the PICTURE string. If the field contains
Date/Time/Timestamp data, the type qualifier specifies the format of the data.
For example, a type qualifier of ddMMyyyy indicates that the data is formatted
as follows: 02011999 is January 2, 1999.
The DLITypeInfo class defines several constants that can be supplied as
values for the type argument: DATE, TIME, TIMESTAMP, ZONEDDECIMAL and
PACKEDDECIMAL.
Parameters:
fieldName - The name of the field.
typeQualifier - The type qualifier for the field.
type - The type of the field.
startingOffset - The starting offset in the I/O area of this field,
beginning at offset 1.
length - The length of the field for a PACKEDDECIMAL number, the
length can be calculated with the following function: ceiling((number
of digits + 1)/2) for a ZONEDDECIMAL number, the length can be
calculated with the following function: number of digits + 1 (if the
decimal is stored in memory) number of digits (if the decimal is not
stored in memory).
Throws: IllegalArgumentException if the starting offset is less than zero,
an unsupported type is given, or an invalid length is given.
DLITypeInfo (String, String, int, int, int, String)
public DLITypeInfo(String fieldName,
String typeQualifier,
int type,
int startingOffset,
int length,
String searchFieldName)
Constructs a DLITypeInfo object. This constructor is to be used with all key
and search fields of zoned or packed decimal and Date/Time/Timestamp
data. Use the DLITypeInfo(String, String, int, int, int) or
Appendix A. IMS Java package 215

Methods
DLITypeInfo(String, String, int, int, int, String) constructors for all other
types. This constructor provides functionality to provide an alias for the key
and search fields. This alias name is not limited to 8 characters. The uses of
the type qualifier are as follows: If the field type is either packed or zoned
decimal, the type qualifier is the PICTURE string representing the layout of
the field. All COBOL PICTURE strings containing valid combinations of 9s.
Ps, Vs, and Ss are supported. For zoned decimal numbers, the decimal point
(.) can also be used in the PICTURE string. If the field contains
Date/Time/Timestamp data, the type qualifier specifies the format of the data.
For example, a type qualifier of ddMMyyyy indicates that the data is formatted
as follows: 02011999 is January 2, 1999.
The DLITypeInfo class defines several constants that can be supplied as
values for the type argument: DATE, TIME, TIMESTAMP, ZONEDDECIMAL and
PACKEDDECIMAL.
Parameters:
216 IMS Version 7 and Java Application Programming
fieldName - The name of the field. This name can be an alias that
maps to the the actual name as defined in the DBD source file,
which is given by the searchFieldName parameter.
typeQualifier - The type qualifier for the field.
type - The type of the field.
startingOffset - The starting offset in the I/O area of this field,
beginning at offset 1.
length - The length of the field.
searchFieldName - The name of the search or key field exactly as
defined in the DBD source file.
Throws: IllegalArgumentException if the starting offset is less than
zero, an unsupported type is given, or an invalid length is given.
getFieldLength ()
public int getFieldLength()
Returns the length of the field's value in the segment.
Returns: The length, in bytes.

getFieldName ()
public String getFieldName()
Returns the field name given to this field in the segment.
Returns: The name of the field.
getFieldOffset ()
public int getFieldOffset()
Returns the offset of the field in the segment's I/O area.
Returns: The zero-based offset.
getFieldType ()
public int getFieldType()
Returns the type assigned to a field's value in the segment.
Returns: The type.
getSearchFieldName ()
public String getSearchFieldName()
Returns the search field name given to this field in the segment, which
must be exactly as defined in the DBD source file.
Returns: The name of the search field as defined in the DBD source
file.
getTypeQualifier ()
public String getTypeQualifier()
Returns the type qualifier for this type.
Returns: The type qualifier.
A.13 Class com.ibm.ims.base.DLITypeInfoList
java.lang.Object
+----com.ibm.ims.base.DLITypeInfo
+----com.ibm.ims.base.DLITypeInfoList
public class DLITypeInfoList extends DLITypeInfo
A DLITypeInfoList object is a specialization of a DLITypeInfo object that
defines a set of fields that occur more than once. You construct a
DLITypeInfoList object by providing the offset and entire length of the fields
Appendix A. IMS Java package 217

Constructors
that repeat, as well as a count of the number of occurrences of the repeating
fields. The following example demonstrates how to define a ModelOutput
message containing a variable number of entries for Make, Model, and Color
(Figure 117). The total message will be 6004 bytes long and can contain a
maximum of 100 60 byte entries of Make, Model, and Color.
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[] modelOutputTypeInfo = {
new DLITypeInfo ("ModelCount", DLITypeInfo.INTEGER, 1, 4),
new DLITypeInfoList ("ModelList", modelTypeInfo, 5, 60, 100)
};
public ModelOutput() {
super(modelOutputTypeInfo, 6004, false);
}
}
Figure 117. Example defining an OutputModel message
DLITypeInfoList(String, DLITypeInfo[ ], int, int, int)
public DLITypeInfoList(String listName,
DLITypeInfo typeInfo[],
int startingOffset,
int length,
int count)
Constructs a DLITypeInfoList object
Parameters:
218 IMS Version 7 and Java Application Programming
listName - The name of the repeating set of fields.
startingOffset - The starting offset in the I/O area of this set of
fields, beginning at offset 1.
length - The length, in bytes, of one instance of this set of fields.
count - The number of times the fields repeat.
Throws: IllegalArgumentException if the starting offset is less than zero,
or an invalid length is given.

Methods
getCount ()
public final int getCount()
Returns the count of repeating fields.
Returns: The count.
A.14 Class com.ibm.ims.base.IMSErrorMessages
Constructor
Methods
java.lang.Object
+----java.util.ResourceBundle
+----java.util.ListResourceBundle
+----com.ibm.ims.base.IMSErrorMessages
public class IMSErrorMessages extends ListResourceBundle
IMSErrorMessages ()
public IMSErrorMessages()
Creates a resource bundle for giving error messages.
getContents ()
protected Object[][] getContents()
Overrides: getContents in class ListResourceBundle.
getIMSBundle ()
public static IMSErrorMessages getIMSBundle()
Returns the translated resource bundle.
Returns: com.ibm.ims.base.IMSErrorMessages.
getString (String, Object [ ])
public String getString(String key,
Object inserts[ ])
Appendix A. IMS Java package 219

A.15 Class com.ibm.ims.base.IMSInfo
Methods
java.lang.Object
+----com.ibm.ims.base.IMSInfo
public final class IMSInfo extends Object
The IMSInfo class provides information about the application’s current
execution environment. This information is determined by making the System
Service Call INQY with the ENVIRON subfunction. This includes the IMS
identifier, release, region, program name, PSB name, transaction name, user
identifier, group name, and status group indicator.
applicationRegionType ()
public String applicationRegionType()
Returns IMS active application region type. The active region could be
BATCH (IMS Batch), BMP (Batch Message Processing), IFP (IMS Fast Path)
or MPP (Message Processing).
Returns: The active IMS application region type.
controlRegionType ()
public String controlRegionType()
Returns the active IMS Control Region Type. The active region type could
be BATCH (IMS Batch), DB (only the IMS Database Manager is active --
DBCTL system), TM (only the IMS Transaction Manager is active -- DCCTL
system), or DB/DC (both the IMS Database and Transaction managers are
active -- DB/DC system),
Returns: the active IMS Control Region Type.
getIMSInfo ()
public static final IMSInfo getIMSInfo() throws IMSException
Creates an IMSInfo object containing information about the IMS system.
Returns: A new IMSInfo object containing the IMS system information.
Throws: IMSException if a non-blank status code is returned from the
system call.
220 IMS Version 7 and Java Application Programming

groupName ()
public String groupName()
Returns the Group Name.
Returns: The Group Name or blanks if the Group Name is unavailable.
programName ()
public String programName()
Returns the Application Program Name of the application program being
run.
Returns: The Application Program Name.
psbName ()
public String psbName()
Returns the name of the PSB currently allocated.
Returns: The PSB name.
regionID ()
public int regionID()
Returns the IMS Region Identifier.
Returns: The IMS Region Identifier.
releaseLevel ()
public int releaseLevel()
Returns IMS Release Level. For example, for IMS Versio 7 Release 1, 710
will be returned.
Returns: The Release Level for IMS.
statusGroupIndicator ()
public String statusGroupIndicator()
Returns the Status Group Indicator. The indicator could be A (INIT
STATUS GROUPA call is issued), B (INIT STATUS GROUPB call is
issued).
Returns: IMS Status Group indicator or blank if a status group is not
initialized.
systemID ()
public String systemID()
Returns the identifier from the execute parameters.
Appendix A. IMS Java package 221

Returns: The IMS system Identifier.
transactionName ()
public String transactionName()
Returns the name of the transaction.
Returns: The transaction name or blanks if there is no transaction.
userID ()
public String userID()
Returns the user ID derived from the PSTUSID field of the PST that
represents the region making the INQY ENVIRON call.
Returns: The user ID or blanks if the user ID is unavailable.
A.16 Class com.ibm.ims.base.IMSTrace
java.lang.Object
+----com.ibm.ims.base.IMSTrace
public class IMSTrace extends Object
IMSTrace provides tracing facilities to document the flow of control in an IMS
Java application.
The static public variable IMSTrace.traceOn determines whether tracing is
enabled or not. By default IMSTrace.traceOn is set to false. If an application
wishes to utilize tracing, it should set this variable to true within a static block
of their IMSApplication subclass.
The static public variable IMSTrace.libTraceLevel determines the amount of
tracing that will occur within IMS provided packages. If libTraceLevel is zero,
no library tracing occurs. IMSTrace defines three levels of three types of
tracing constants which are used within library provided code. These
constants represent progressively more tracing at each successive level.
Generally, level 1 constants are used for larger objects while level 3
constants are used for smaller objects or high volume functions. The higher
the value of IMSTrace.libTraceLevel, the more trace data will be written to the
output stream. In addition, IMSTrace defines the constant TRACE_EXCEPTIONS.
This level 0 constant is used to trace the construction of library provided
exceptions. The following traceLevel constants represent successively higher
levels of tracing:
222 IMS Version 7 and Java Application Programming

TRACE_EXCEPTIONS Causes tracing of exception construction.
TRACE_CTOR1 Causes tracing of level 1 constructors.
TRACE_METHOD1 Causes tracing of level 1 methods and
constructors.
TRACE_DATA1 Causes tracing of level 1 parameters, return
values, methods, and constructors.
TRACE_CTOR2 Causes tracing of level 2 constructors and all level
1 entries.
TRACE_METHOD2 Causes tracing of level 2 methods and
constructors, and all level 1 entries.
TRACE_DATA2 Causes tracing of level 2 parameters, return
values, methods, constructors, and all level 1
entries.
TRACE_CTOR3 Causes tracing of level 3 constructors and all level
1 and level 2 entries.
TRACE_METHOD3 Causes tracing of level 3 methods and
constructors, and all level 1 and level 2 entries.
TRACE_DATA3 Causes tracing of level 3 parameters, return
values, methods, constructors, and all level 1 and
level 2 entries.
By default, IMSTrace.libTraceLevel is set to TRACE_EXCEPTIONS. If an application
wishes to change the amount of tracing within the IMS library provided
packages, it should update this variable within a static block of their
IMSApplication subclass.
An application can control the output location used for tracing by calling
IMSTrace.setOutputStream with a valid print stream or by calling
IMSTrace.setOutputWriter with a valid character output stream. One of these
function should be called within a static block of an IMSApplication subclass.
Figure 118 shows how to use System.out for trace output and set
libTraceLevel to TRACE_DATA2.
Appendix A. IMS Java package 223

public class MyApplication extends IMSApplication {
static {
IMSTrace.traceOn = true;
IMSTrace.setOutputStream(System.out);
IMSTrace.libTraceLevel=IMSTrace.TRACE_DATA2;
}
public abstract void doBegin() throws com.ibm.ims.base.IMSException {
...
}
} // end MyApplication
Figure 118. Using System.out for trace output
IMSTrace.logData is the primary method for writing trace data. If either
IMSTrace.setOutputStream or IMSTrace.setOutputWriter was called with a valid
output stream, and IMSTrace.traceOn is set to true, logData writes its string
data to this stream. If an error occurs writing to one of these streams, or
tracing is enabled and a stream has not been provided, the trace data is
written to the System.err stream. Prior to writing its data to an output stream,
IMSTrace.logData prepends a newline character and a number of blank
characters based on the current nested method level.
The IMS library provided packages utilize XML tags when logging its data.
The following tags are used:
methodName A method entry
methodName A method exit
A parameter
parmName The name of a parameter
parmCharValue Character data for a
parameter
parmHexValue Hex data for a parameter
Data
dataName The name of a data value
dataCharValue Character data value
dataHexValue Hex data value
The result of a method
resultCharValue Character result value
resultHexValue Hex result value
224 IMS Version 7 and Java Application Programming

Variables
As a convenience, IMSTrace contains logging methods that add some of the
appropriate XML tags prior to writing the data to the log. These include:
logEntry Adds the tags
logExit Adds the tags
logParms Adds the , ,
, tags
logData Adds the , ,
, tags
logResult Adds the ,
, tags
To write to the IMSTrace, you need to get an IMSTrace object by calling the
method IMSTrace.currentTrace. For example:
IMSTrace.currentTrace().logData(“dataName”, “dataValue”);
Some of the IMS library supplied packages implement tracing using “Trace”
subclasses. These subclasses re-implement the methods in the base class
needing to be traced by wrapping IMSTrace calls around the calls to the base
class methods. In addition, prior to instantiating an object implementing
tracing, a test is made to see if tracing is enabled. If tracing is enabled, the
“Trace” subclass is instantiated instead of the base class. This style of tracing
is limited to classes that hide their constructors and support object creation
using “createInstance” style methods on the class (or on a related class).
Tracing the entry point of constructors in Java is made difficult by the
language requirement that the first line of a constructor be a call to its super
class constructor. The result of this behavior is that the trace will show an
entry and exit of the base class constructor prior to showing an entry to the
derived class constructor.
traceOn
public static boolean traceOn
The flag to indicate whether tracing is enabled.
Appendix A. IMS Java package 225

TRACE_EXCEPTIONS
public static final int TRACE_EXCEPTIONS
Causes tracing of Exception constructors.
TRACE_CTOR1
public static final int TRACE_CTOR1
Causes tracing of level 1 constructors.
TRACE_METHOD1
public static final int TRACE_METHOD1
Causes tracing of level 1 methods and constructors.
TRACE_DATA1
public static final int TRACE_DATA1
Causes tracing of level 1 parameters, return values, methods, and
constructors.
TRACE_CTOR2
public static final int TRACE_CTOR2
Causes tracing of level 2 constructors and all level 1 entries.
TRACE_METHOD2
public static final int TRACE_METHOD2
Causes tracing of level 2 methods and constructors, and all level 1 entries.
TRACE_DATA2
public static final int TRACE_DATA2
Causes tracing of level 2 parameters, return values, methods,
constructors, and all level 1 entries.
TRACE_CTOR3
public static final int TRACE_CTOR3
Causes tracing of level 3 constructors and all level 1 and level 2 entries.
TRACE_METHOD3
public static final int TRACE_METHOD3
Causes tracing of level 3 methods and constructors, and all level 1 and
level 2 entries.
226 IMS Version 7 and Java Application Programming

Methods
TRACE_DATA3
public static final int TRACE_DATA3
Causes tracing of level 3 parameters, return values, methods,
constructors, and all level 1 and level 2 entries.
libTraceLevel ()
public static int libTraceLevel
The trace level for IMS Library code.
currentTrace ()
public static IMSTrace currentTrace()
Returns the IMSTrace object for the current thread.
Returns: The IMSTrace object for the current thread.
setOutputStream (PrintStream)
public static void setOutputStream(PrintStream outputStream)
Sets the output stream used for tracing to a print stream. If neither a
character output stream nor print stream has been set, and tracing is
enabled, the trace data is written to the System.err stream.
Parameters:
outputStream - A PringStream for tracing.
setOutputWriter (Writer)
public static void setOutputWriter(Writer outputStream)
Sets the output stream used for tracing to a character output stream. If
neither a character output stream nor a print stream has been set, and
tracing is enabled, the trace data is written to the System.err stream.
Parameters:
outputStream - An output stream for tracing.
getOutputStream ()
public static PrintStream getOutputStream()
Returns the print stream used for tracing or null if a print stream has not
been set. It also returns null if a character output stream has been set
using setOutputWriter. If neither a character output stream nor a print
stream has been set, and tracing is enabled, the trace data is written to
the System.err stream.
Appendix A. IMS Java package 227

Returns: An output stream or null if an output stream has not been set.
getOutputWriter ()
public static Writer getOutputWriter()
Returns the character output stream used for tracing or null if a character
output stream has not been set. It also returns null if a print stream has
been set using setOutputStream. If neither a character output stream nor a
print stream has been set, and tracing is enabled, the trace data is written
to the System.err stream.
Returns: A character output stream or null if an output stream has not
been set.
setMaxBinaryLength (int)
public static void setMaxBinaryLength(int maxBinaryLength)
Sets the maximum length when tracing binary data. If not called by an
application, the maximum length of binary data traced is 50 bytes.
getMaxBinaryLength ()
public static int getMaxBinaryLength()
Returns the maximum length when tracing binary data (e.g. a byte array).
If setMaxBinaryLength has not bee called by an application, the maximum
length of binary data traced is 50 bytes.
Returns: The maximum length traced for binary data.
setTIDTracing (boolean)
public static void setTIDTracing(boolean on)
Adds or removes the thread identifier to trace entries. This value must be
set before any trace activity and before a call to IMSTrace.currentTrace. It
is recommended that this method be used within a static block of the main
application class.
logData (String)
public void logData(String entry)
Writes a trace entry. If IMSTrace.traceOn is true and an output stream has
been established, the trace data is written to that output stream. The
output stream can be either a print stream, set by calling setOutputStream,
or a character output stream, set by calling setOutputWriter. If traceOn is
true and an output stream has not been established, the trace data is
written to the System.err stream.
228 IMS Version 7 and Java Application Programming

Parameters:
entry - The string to write to the log.
logEntry (String)
public void logEntry(String methodName)
Writes a method entry point. This method adds XML tags for an entry point
prior to writing the method name to the log.
Parameters:
methodName - The method being entered.
logExit (String)
public void logExit(String methodName)
Writes a method exit point. This method adds XML tags for an exit point
prior to writing the method name to the log.
Parameters:
methodName - The method being entered.
logResult (String)
public void logResult(String result)
Writes the result of a method. This method adds XML tags for a result prior
to writing the result to the log.
Parameters:
result - The result to be written.
logResult (byte)
public void logResult(byte result[])
Writes the byte array result of a method. This method adds XML tags for a
result prior to writing the result to the log and it dumps the byte array as
hex characters.
Parameters:
result - The result to be written in hex.
logParm (String, byte)
public void logParm(String parmName,
byte parmValue[])
Writes the parameters of a method. This method adds XML tags for a
parameter, and optionally the value of the parameter, prior to writing the
parameter to the log.
Appendix A. IMS Java package 229

Parameters:
parmName - The name of the parameter.
230 IMS Version 7 and Java Application Programming
parmValue - The string value of the parameter or null.
logData (String, String)
public void logData(String dataName,
String dataValue)
Writes a data name-value pair. This method adds XML tags for the data
and the value of the data prior to writing the data to the log.
Parameters:
dataName - The name of the data to be written.
dataValue - The value of the data to be written.
logData (String, byte)
public void logData(String dataName,
byte dataValue[])
Writes a data value in binary and character. This method adds XML tags
for the data name and value prior to writing the parameter to the log.
Parameters:
dataName - The name of the parameter.
dataValue - The byte array value null.
logParm (String, String)
public void logParm(String parmName,
String parmValue)
Writes the parameters of a method. This method adds XML tags for a
parameter, and optionally the value of the parameter, prior to writing the
parameter to the log.
Parameters:
parmName - The name of the parameter.
parmValue - The string value of the parameter or null.
logParm (String, String, String, String)
public void logParm(String parm1Name,
String parm1Value,
String parm2Name,
String parm2Value)

Writes the parameters of a method. This method adds XML tags for two
parameters, and optionally the value of these parameters, prior to writing
them to the log.
Parameters:
parm1Name - The name of the first parameter.
parm1Value - The string value of the first parameter or null.
parm2Name - The name of the second parameter.
parm2Value - The string value of the second parameter or null.
logParm (String, String, String, String, String, String)
public void logParm(String parm1Name,
String parm1Value,
String parm2Name,
String parm2Value,
String parm3Name,
String parm3Value)
Writes the parameters of a method. This method adds XML tags for three
parameters, and optionally the value of these parameters, prior to writing
them to the log.
Parameters:
parm1Name - The name of the first parameter.
parm1Value - The string value of the first parameter or null.
parm2Name - The name of the second parameter.
parm2Value - The string value of the second parameter or null.
parm3Name - The name of the third parameter.
parm3Value - The string value of the third parameter or null.
logParm (String, String)
public void logParm(String parmNameArray[ ],
String parmValueArray[ ])
Writes the parameters of a method. This method adds XML tags for an
array of parameter names, and optionally the value of these parameters,
prior to writing them to the log.
Parameters:
parmArray - The array of parameter names.
parmValueArray - The array of string values of the parameters or null.
Appendix A. IMS Java package 231

A.17 Class com.ibm.ims.base.IOPCB
Methods
java.lang.Object
+----com.ibm.ims.base.IOPCB
public final class IOPCB extends Object
The IOPCB class contains all the data attributes of the IMS I/O Program
Communication Block and the necessary getter and setter method. IMS
describes the results of the calls your program issues in the I/O PCB that is
referenced in the call. For more information, see IMS Application
Programming: Transaction Manager.
getLogicalTerminalName ()
public String getLogicalTerminalName()
Returns the logical terminal name in this IOPCB. The maximun length is 8
characters.
Returns: The IOPCB’s logical terminal name.
getStatusCode ()
public short getStatusCode()
Returns the status code from the last DLI call using this IOPCB.
Returns: The IOPCB’s IMS status code.
getLocalDate ()
public String getLocalDate()
Returns the local date from the last DLI call using this IOPCB. The local
date is in the format yyddd.
Returns: The IOPCB’s local date.
getLocalTime ()
public String getLocalTime()
Returns the local time from the last DLI call using this IOPCB. The local
time is in the format hhmmsst.
Returns: The IOPCB’s local time.
232 IMS Version 7 and Java Application Programming

getInputMessageSequenceNumber ()
public int getInputMessageSequenceNumber()
Returns the input message sequence number from the last DLI call using
this IOPCB.
Returns: The IOPCB’s input message sequence number.
getMODName ()
public String getMODName()
Returns the message output descriptor (MOD) name from the last DLI call
using this IOPCB. The maximum length is 8 characters.
Returns: The IOPCB’s message output descriptor (MOD) name.
getUserid ()
public String getUserid()
Returns the userid from the last DLI call using this IOPCB. The maximum
length is 8 characters.
Returns: The IOPCB’s userid.
getGroupName ()
public String getGroupName()
Returns the group name from the last DLI call using this IOPCB. The
maximum length is 8 characters.
Returns: The IOPCB’s group name.
A.18 Class com.ibm.ims.base.JavaToDLI
java.lang.Object
+----com.ibm.ims.base.JavaToDLI
public final class JavaToDLI extends Object
The JavaToDLI class is used to issue DL/I calls to get, update, insert, and
delete data in IMS databases, to get and insert messages to the IMS
message queues, and to perform IMS system service calls. JavaToDLI is
defined as public final. This class also loads the native code DLL in a static
block.
Appendix A. IMS Java package 233

Variables
A1
public static final short A1
A2
public static final short A2
A3
public static final short A3
A4
public static final short A4
A5
public static final short A5
A6
public static final short A6
A7
public static final short A7
A8
public static final short A8
A9
public static final short A9
AA
public static final short AA
AB
public static final short AB
AC
public static final short AC
AD
public static final short AD
AF
public static final short AF
234 IMS Version 7 and Java Application Programming

AG
public static final short AG
AH
public static final short AH
AI
public static final short AI
AJ
public static final short AJ
AK
public static final short AK
AL
public static final short AL
AM
public static final short AM
AO
public static final short AO
AP
public static final short AP
AQ
public static final short AQ
AR
public static final short AR
AS
public static final short AS
AT
public static final short AT
AU
public static final short AU
Appendix A. IMS Java package 235

AX
public static final short AX
AY
public static final short AY
AZ
public static final short AZ
BA
public static final short BA
BB
public static final short BB
BC
public static final short BC
BJ
public static final short BJ
BK
public static final short BK
CA
public static final short CA
CB
public static final short CB
CC
public static final short CC
CD
public static final short CD
CE
public static final short CE
CF
public static final short CF
236 IMS Version 7 and Java Application Programming

CG
public static final short CG
CH
public static final short CH
CI
public static final short CI
CJ
public static final short CJ
CK
public static final short CK
CL
public static final short CL
CM
public static final short CM
CN
public static final short CN
DA
public static final short DA
DJ
public static final short DJ
DX
public static final short DX
FA
public static final short FA
FC
public static final short FC
FD
public static final short FD
Appendix A. IMS Java package 237

FE
public static final short FE
FF
public static final short FF
FG
public static final short FG
FH
public static final short FH
FI
public static final short FI
FM
public static final short FM
FN
public static final short FN
FP
public static final short FP
FR
public static final short FR
FS
public static final short FS
FT
public static final short FT
FV
public static final short FV
FW
public static final short FW
FY
public static final short FY
238 IMS Version 7 and Java Application Programming

GA
public static final short GA
GB
public static final short GB
GC
public static final short GC
GD
public static final short GD
GE
public static final short GE
GG
public static final short GG
GK
public static final short GK
GL
public static final short GL
GP
public static final short GP
II
public static final short II
IX
public static final short IX
LB
public static final short LB
LC
public static final short LC
LD
public static final short LD
Appendix A. IMS Java package 239

LE
public static final short LE
MR
public static final short MR
NA
public static final short NA
NE
public static final short NE
NI
public static final short NI
NL
public static final short NL
NO
public static final short NO
NU
public static final short NU
QC
public static final short QC
QD
public static final short QD
QE
public static final short QE
QF
public static final short QF
QH
public static final short QH
RA
public static final short RA
240 IMS Version 7 and Java Application Programming

RC
public static final short RC
RX
public static final short RX
SA
public static final short SA
SB
public static final short SB
SC
public static final short SC
SY
public static final short SY
TA
public static final short TA
TC
public static final short TC
TE
public static final short TE
TG
public static final short TG
TH
public static final short TH
TI
public static final short TI
TJ
public static final short TJ
TL
public static final short TL
Appendix A. IMS Java package 241

TN
public static final short TN
TO
public static final short TO
TP
public static final short TP
TR
public static final short TR
TY
public static final short TY
TZ
public static final short TZ
UC
public static final short UC
UR
public static final short UR
US
public static final short US
UX
public static final short UX
V1
public static final short V1
V2
public static final short V2
V3
public static final short V3
V4
public static final short V4
242 IMS Version 7 and Java Application Programming

V5
public static final short V5
V6
public static final short V6
V7
public static final short V7
X2
public static final short X2
X3
public static final short X3
X4
public static final short X4
X5
public static final short X5
X6
public static final short X6
X7
public static final short X7
X8
public static final short X8
XA
public static final short XA
XB
public static final short XB
XC
public static final short XC
XD
public static final short XD
Appendix A. IMS Java package 243

XE
public static final short XE
XF
public static final short XF
XG
public static final short XG
XX
public static final short XX
JNI1
public static final short JNI1
JNI2
public static final short JNI2
JNI3
public static final short JNI3
JNI4
public static final short JNI4
AUTH_CLASS_CHNG_DESTINATION
public static final short AUTH_CLASS_CHNG_DESTINATION
CHNG_WITH_INVALID_PCB
public static final short CHNG_WITH_INVALID_PCB
PCB_DESTINATION
public static final short PCB_DESTINATION
CONVERSATIONAL_RESPONSE_SECURITY
public static final short CONVERSATIONAL_RESPONSE_SECURITY
MODNAME_SUBSEQUENT_MESSAGE
public static final short MODNAME_SUBSEQUENT_MESSAGE
MESSAGE_SEGMENT_SIZE_EXCEEDED
public static final short MESSAGE_SEGMENT_SIZE_EXCEEDED
244 IMS Version 7 and Java Application Programming

NUMBER_OF_OUTPUT_SEGMENTS_EXCEEDED
public static final short NUMBER_OF_OUTPUT_SEGMENTS_EXCEEDED
INSERT_TO_IOPCB_AND_ALTERNATE_PCB
public static final short INSERT_TO_IOPCB_AND_ALTERNATE_PCB
ALTERNATE_PCB_PHYSICAL_TERMINAL
public static final short ALTERNATE_PCB_PHYSICAL_TERMINAL
ALTERNATE_RESPONSE_DESTINATION
public static final short ALTERNATE_RESPONSE_DESTINATION
MISSING_IO_AREA
public static final short MISSING_IO_AREA
SSA_HIERARCHIC_ERROR
public static final short SSA_HIERARCHIC_ERROR
INVALID_FUNCTION_FOR_PCB
public static final short INVALID_FUNCTION_FOR_PCB
GSAM_INVALID_RECORD_LENGTH
public static final short GSAM_INVALID_RECORD_LENGTH
INQY_IO_LENGTH
public static final short INQY_IO_LENGTH
REQUIRED_SSA_MISSING
public static final short REQUIRED_SSA_MISSING
DATA_MANAGEMENT_OPEN_ERROR
public static final short DATA_MANAGEMENT_OPEN_ERROR
INVALID_SSA_OR_PARAMETER
public static final short INVALID_SSA_OR_PARAMETER
SSA_FIELDNAME_ERROR
public static final short SSA_FIELDNAME_ERROR
IOPCB_IN_BATCH
public static final short IOPCB_IN_BATCH
Appendix A. IMS Java package 245

INCOMPATIBLE_CALL_FUNCTION
public static final short INCOMPATIBLE_CALL_FUNCTION
PHYSICAL_IO_ERROR
public static final short PHYSICAL_IO_ERROR
PARAMETER_LIMIT
public static final short PARAMETER_LIMIT
INVALID_SUB_FUNCTION
public static final short INVALID_SUB_FUNCTION
OPTIONS_LIST_ERROR
public static final short OPTIONS_LIST_ERROR
IAFP_ERROR
public static final short IAFP_ERROR
IO_AREA_LENGTH
public static final short IO_AREA_LENGTH
SSA_TOTAL_LENGTH
public static final short SSA_TOTAL_LENGTH
SYSTEM_ERROR
public static final short SYSTEM_ERROR
MULTIPLE_PHYSICAL_TERMINAL
public static final short MULTIPLE_PHYSICAL_TERMINAL
PURG_IGNORED
public static final short PURG_IGNORED
UNAVAILABLE_DATA
public static final short UNAVAILABLE_DATA
UNAVAILABLE_DATA_WITH_BACKOUT
public static final short UNAVAILABLE_DATA_WITH_BACKOUT
DEADLOCK_WITH_BACKOUT
public static final short DEADLOCK_WITH_BACKOUT
246 IMS Version 7 and Java Application Programming

ALL_DATABASES_UNAVAILABLE
public static final short ALL_DATABASES_UNAVAILABLE
DATABASE_IN_PCB_UNAVAILABLE
public static final short DATABASE_IN_PCB_UNAVAILABLE
INVALID_COMMAND
public static final short INVALID_COMMAND
AOI_COMMAND
public static final short AOI_COMMAND
COMMAND_RESPONSE_RETURNED
public static final short COMMAND_RESPONSE_RETURNED
COMMAND_SECURITY
public static final short COMMAND_SECURITY
MESSAGE_RESCHEDULED
public static final short MESSAGE_RESCHEDULED
MESSAGE_QUEUED_PRIOR_TO_LAST_START
public static final short MESSAGE_QUEUED_PRIOR_TO_LAST_START
MESSAGE_ORIGINATED_FROM_AOI_EXIT
public static final short MESSAGE_ORIGINATED_FROM_AOI_EXIT
AOI_COMMAND_IGNORED
public static final short AOI_COMMAND_IGNORED
MESSAGE_QUEUED_PRIOR_RESCHEDULED
public static final short MESSAGE_QUEUED_PRIOR_RESCHEDULED
MESSAGE_FROM_AOI_EXIT_RESCHEDULED
public static final short MESSAGE_FROM_AOI_EXIT_RESCHEDULED
MESSAGE_QUEUED_PRIOR_FROM_AOI_EXIT
public static final short MESSAGE_QUEUED_PRIOR_FROM_AOI_EXIT
AOI_EXIT_MESSAGE_QUEUED_PRIOR_RESCHEDULED
public static final short AOI_EXIT_MESSAGE_QUEUED_PRIOR_RESCHEDULED
Appendix A. IMS Java package 247

WKAP_INSUFFICIENT
public static final short WKAP_INSUFFICIENT
IOASIZE_TOO_SMALL
public static final short IOASIZE_TOO_SMALL
KEY_MODIFICATION
public static final short KEY_MODIFICATION
SEGMENT_NOT_HELD
public static final short SEGMENT_NOT_HELD
SEGMENT_DELETE_RULE
public static final short SEGMENT_DELETE_RULE
DATABASE_ARITHMETIC_OVERFLOW
public static final short DATABASE_ARITHMETIC_OVERFLOW
INVALID_REQUEST_FOR_SEGMENT
public static final short INVALID_REQUEST_FOR_SEGMENT
BMP_DEADLOCK
public static final short BMP_DEADLOCK
FLD_CALL
public static final short FLD_CALL
MSDB_FREE_SPACE
public static final short MSDB_FREE_SPACE
FLD_CALL_BUFFER_SPACE
public static final short FLD_CALL_BUFFER_SPACE
DEDB_AREA_INACCESSIBLE
public static final short DEDB_AREA_INACCESSIBLE
IO_AREA_INACCESSIBLE
public static final short IO_AREA_INACCESSIBLE
RANDOMIZING_ROUTINE_REQUEST
public static final short RANDOMIZING_ROUTINE_REQUEST
248 IMS Version 7 and Java Application Programming

FLD_FIELD_NAME
public static final short FLD_FIELD_NAME
INVALID_HEXADECIMAL_OR_DECIMAL_DATA
public static final short INVALID_HEXADECIMAL_OR_DECIMAL_DATA
TOTAL_BUFFER_ALLOCATION_EXCEEDED
public static final short TOTAL_BUFFER_ALLOCATION_EXCEEDED
DEDB_AREAS_FULL
public static final short DEDB_AREAS_FULL
SSA_LIMIT_EXCEEDED
public static final short SSA_LIMIT_EXCEEDED
VERIFY_OPERATION
public static final short VERIFY_OPERATION
BMP_BUFFER_SPACE
public static final short BMP_BUFFER_SPACE
BACKWARD_ACCESS_VIOLATION
public static final short BACKWARD_ACCESS_VIOLATION
HIERARCHIC_BOUNDARY
public static final short HIERARCHIC_BOUNDARY
END_OF_DATA
public static final short END_OF_DATA
CROSSING_UOW_BOUNDARY
public static final short CROSSING_UOW_BOUNDARY
UNQUALIFIED_INSERT
public static final short UNQUALIFIED_INSERT
SEGMENT_NOT_FOUND
public static final short SEGMENT_NOT_FOUND
INVALID_SEGMENT_POINTER
public static final short INVALID_SEGMENT_POINTER
Appendix A. IMS Java package 249

DIFFERENT_SEGMENT_TYPE
public static final short DIFFERENT_SEGMENT_TYPE
INVALID_LOG_CODE
public static final short INVALID_LOG_CODE
PARENTAGE_NOT_ESTABLISHED
public static final short PARENTAGE_NOT_ESTABLISHED
DUPLICATE_SEGMENT
public static final short DUPLICATE_SEGMENT
SEGMENT_INSERT_RULE
public static final short SEGMENT_INSERT_RULE
DUPLICATE_SEGMENT_LOAD
public static final short DUPLICATE_SEGMENT_LOAD
KEY_SEQUENCE
public static final short KEY_SEQUENCE
PARENT_NOT_LOADED
public static final short PARENT_NOT_LOADED
SIBLING_SEQUENCE
public static final short SIBLING_SEQUENCE
RESERVED
public static final short RESERVED
DATABASE_UNAVAILABLE
public static final short DATABASE_UNAVAILABLE
SEGMENT_NOT_FOUND_BY_INDEX_MAINTENACE
public static final short SEGMENT_NOT_FOUND_BY_INDEX_MAINTENACE
DUPLICATE_SEGMENT_SECONDARY_INDEX
public static final short DUPLICATE_SEGMENT_SECONDARY_INDEX
LOG_DATASET_DD_MISSING
public static final short LOG_DATASET_DD_MISSING
250 IMS Version 7 and Java Application Programming

INDEX_MAINTENANCE_IO_ERROR
public static final short INDEX_MAINTENANCE_IO_ERROR
DATABASE_UNAVAILABLE_FOR_UPDATE
public static final short DATABASE_UNAVAILABLE_FOR_UPDATE
END_OF_MESSAGES
public static final short END_OF_MESSAGES
END_OF_MESSAGE_SEGMENTS
public static final short END_OF_MESSAGE_SEGMENTS
CALL_SEQUENCE
public static final short CALL_SEQUENCE
SEGMENT_LENGTH
public static final short SEGMENT_LENGTH
TERMINAL_SYMBOLIC_ERROR
public static final short TERMINAL_SYMBOLIC_ERROR
UNMATCHED_TOKEN
public static final short UNMATCHED_TOKEN
ROLS_UNSUPPORTED_PCB
public static final short ROLS_UNSUPPORTED_PCB
SEGMENT_REPLACE_RULE
public static final short SEGMENT_REPLACE_RULE
SETS_REQUEST_STORAGE_EXCEEDED
public static final short SETS_REQUEST_STORAGE_EXCEEDED
SETS_LEVELS_EXCEEDED
public static final short SETS_LEVELS_EXCEEDED
SETS_UNSUPPORTED_PCB
public static final short SETS_UNSUPPORTED_PCB
SYNC_FAILURE
public static final short SYNC_FAILURE
Appendix A. IMS Java package 251

PSB_DIRECTORY
public static final short PSB_DIRECTORY
PSB_ALREADY_SCHEDULED
public static final short PSB_ALREADY_SCHEDULED
PSB_INITIALIZATION_ERROR
public static final short PSB_INITIALIZATION_ERROR
TERMINATE_UNSCHEDULED_PSB
public static final short TERMINATE_UNSCHEDULED_PSB
DATABASE_ACCESS_WITH_UNSCHEDULED_PSB
public static final short DATABASE_ACCESS_WITH_UNSCHEDULED_PSB
INVALID_PATH_TO_SEGMENT
public static final short INVALID_PATH_TO_SEGMENT
DLI_NOT_ACTIVE
public static final short DLI_NOT_ACTIVE
SCHEDULING_INTENT_CONFLICT
public static final short SCHEDULING_INTENT_CONFLICT
INVALID_SDIB
public static final short INVALID_SDIB
PATH_REPLACE_ERROR
public static final short PATH_REPLACE_ERROR
INVALID_PCB_NUMBER_OR_PROC_OPTIONS
public static final short INVALID_PCB_NUMBER_OR_PROC_OPTIONS
XDLIPRE
public static final short XDLIPRE
DATABASE_NOT_OPEN
public static final short DATABASE_NOT_OPEN
SEGMENT_EXCEEDS_64K
public static final short SEGMENT_EXCEEDS_64K
252 IMS Version 7 and Java Application Programming

CHECKPOINT_WRITTEN_TO_UCF
public static final short CHECKPOINT_WRITTEN_TO_UCF
PROGRAM_RESTARTED_UNDER_UCF
public static final short PROGRAM_RESTARTED_UNDER_UCF
UCF_STOP
public static final short UCF_STOP
CHECKPOINT_AND_STOP
public static final short CHECKPOINT_AND_STOP
VARIABLE_SEGMENT_LENGTH
public static final short VARIABLE_SEGMENT_LENGTH
INVALID_SEGMENT_LENGTH
public static final short INVALID_SEGMENT_LENGTH
INVALID_FIELD_LENGTH
public static final short INVALID_FIELD_LENGTH
INVALID_VARIABLE_SEGMENTLENGTH
public static final short INVALID_VARIABLE_SEGMENTLENGTH
INVALID_OFFSET
public static final short INVALID_OFFSET
INVALID_CONCATENATED_KEY_LENGTH
public static final short INVALID_CONCATENATED_KEY_LENGTH
INVALID_STATISTICS_AREA_LENGTH
public static final short INVALID_STATISTICS_AREA_LENGTH
FIRST_INSERT_TO_ALTERNATE_PCB_NOT_SPA
public static final short FIRST_INSERT_TO_ALTERNATE_PCB_NOT_SPA
INVALID_SPA
public static final short INVALID_SPA
INVALID_SPA_DESTINATION
public static final short INVALID_SPA_DESTINATION
Appendix A. IMS Java package 253

MULTIPLE_SPAS_PERMESSAGE
public static final short MULTIPLE_SPAS_PERMESSAGE
INVALID_SPA_TRANSACTION_CODE
public static final short INVALID_SPA_TRANSACTION_CODE
INVALID_SPA_LENGTH
public static final short INVALID_SPA_LENGTH
SPA_IO_ERROR
public static final short SPA_IO_ERROR
INVALID_SPA_PASS
public static final short INVALID_SPA_PASS
INVALID_SPA_RESPOND
public static final short INVALID_SPA_RESPOND
INVALID_Z1_FIELD
public static final short INVALID_Z1_FIELD
IMS_TERMINATING
public static final short IMS_TERMINATING
INSERT_SPA_TO_EXPRESS_PCB
public static final short INSERT_SPA_TO_EXPRESS_PCB
INSERT_TO_SPA_NOT_ALTRESP
public static final short INSERT_TO_SPA_NOT_ALTRESP
FIXED_LENGTH_SPA_ERROR
public static final short FIXED_LENGTH_SPA_ERROR
GSAM_ERROR
public static final short GSAM_ERROR
JavaToDLI ()
public JavaToDLI()
254 IMS Version 7 and Java Application Programming

Methods
decimalToString (byte[], int, int)
public static native String decimalToString(byte decimalData[ ],
int offset,
int length)
execute (String)
public static void execute(String function) throws IMSException
Executes CEETDLI(String function) call. DLI ROLL and TERM calls.
Parameters:
function - DLI function.
Throws: IMSException if IMS status code returned is non-blank.
execute (String, AIB)
public static void execute(String function,
AIB aib) throws IMSException
Executes CEETDLI(String function, AIB aib) call. DLI APSB, CLSE, OPEN, PURG,
and SYNC calls.
Parameters:
function - DLI function.
aib - IMS AIB.
Throws: IMSException if IMS status code returned is non-blank.
execute (String, AIB, byte[ ])
public static void execute(String function,
AIB aib,
byte ioArea[ ]) throws IMSException
Executes CEETDLI(String function, AIB aib, byte[] ioarea) calls. DLI AUTH,
CHKP (basic), CMD, DEQ, FLD, GCMD, GMSG, GSCD, GU, GN, ICMD, INIT, INQY, LOG, OPEN,
POS, PURG, ROLB, RCMD, and SNAP..
Parameters:
function - DLI function.
aib - IMS AIB.
ioArea - Area to pass data to and receive data from IMS.
Throws: IMSException if IMS status code returned is non-blank.
Appendix A. IMS Java package 255

execute (String, AIB, String)
public static void execute(String function,
AIB aib,
String destinationName) throws IMSException
Executes CEETDLI(String function, AIB aib, String destinationName) call.
DLI CHNG.
Parameters:
function - DLI function.
aib - IMS AIB.
destinationName - Terminal name or transaction name.
Throws: IMSException If IMS status code returned is non-blank.
execute (String, AIB, String, byte[])
public static void execute(String function,
AIB aib,
String destinationName,
byte optionsList[]) throws IMSException
Executes CEETDLI(String function, AIB aib, String destinationName,
byte[] optionsList) calls.
Parameters:
function - DLI function.
aib - IMS AIB.
256 IMS Version 7 and Java Application Programming
destinationName - Terminal name or transaction name.
optionsList - Processing options.
Throws: IMSException if IMS status code returned is non-blank.
execute (String, AIB, byte[ ], byte[ ], byte[ ])
public static void execute(String function,
AIB aib,
byte ioArea[ ],
byte optionsList[],
byte feedbackArea[]) throws IMSException
Executes CEETDLI(String function, AIB aib, byte[] ioArea, byte[]
optionsList, byte[] feedbackArea) calls. DLI SETO call.
Parameters:
function - DLI function.
aib - IMS AIB.

optionsList - Processing options.
feedbackArea - Error information returned.
Throws: IMSException if IMS status code returned is non-blank.
execute (String, AIB, String, byte[ ],byte[ ])
public static void execute(String function,
AIB aib,
String destinationName,
byte optionsList[ ],
byte feedbackArea[]) throws IMSException
Executes CEETDLI(String function, AIB aib, String destinationName,
byte[] optionsList, byte[] feedbackArea) calls. DLI CHNG call.
Parameters:
function - DLI function.
aib - IMS AIB.
destinationName - Terminal name or transaction name.
optionsList - Processing options.
feedbackArea - Error information returned.
Throws: IMSException If IMS status code returned is non-blank.
execute (String, AIB, byte[ ], byte [ ])
public static void execute(String function,
AIB aib,
byte ioArea[ ],
byte token[ ]) throws IMSException
Executes CEETDLI(String function, AIB aib, byte[] ioarea, byte[] token)
calls. DLI FLD, ROLS, SETS, SETU, and STAT calls.
Parameters:
function - DLI function.
aib - IMS AIB.
ioArea - Area to pass data to and receive data from IMS.
token - Identifier.
Throws: IMSException if IMS status code returned is non-blank.
Appendix A. IMS Java package 257

execute (String, AIB, byte[ ], byte[ ][ ])
public static void execute(String function,
AIB aib,
byte ioArea[ ],
byte ssaL[ ][ ]) throws IMSException
execute (String, AIB, byte[ ], String)
public static void execute(String function,
AIB aib,
byte ioArea[ ],
String modName) throws IMSException
Executes CEETDLI(String function, AIB aib, byte[] ioArea, String
modName) calls. DLI message ISRT call.
Parameters:
function - DLI function.
aib - IMS AIB.
258 IMS Version 7 and Java Application Programming
ioArea - Area to pass data to and receive data from IMS.
modName - IMS Message Output Descriptor name.
Throws: IMSException if IMS status code returned is non-blank.
checkESAF ()
public static native boolean checkESAF()
doubleToByteArray (double)
public static native byte[] doubleToByteArray(double d)
byteArrayToDouble (byte[ )
public static native double byteArrayToDouble(byte bArr[])
A.19 Class com.ibm.ims.base.DLIJNICallbackException
java.lang.Object
+----java.lang.Throwable
+----java.lang.Exception
+----java.lang.RuntimeException
+----com.ibm.ims.base.DLIJNICallbackException
public class DLIJNICallbackException extends RuntimeException

Method
This exception is thrown to indicate a JNI error has occured while issuing a
DLI call. This is an internal error and should not be caught, but allowed to
abend the IMSJava application.
DLIJNICallbackException ()
public DLIJNICallbackException()
A.20 Class com.ibm.ims.base.DLIWarning
Constructor
java.lang.Object
+----java.lang.Throwable
+----java.lang.Exception
+----com.ibm.ims.base.DLIWarning
public class DLIWarning extends Exception
The DLIWarning class provides information when data was lost due to a type
conversion. For example, a field in an input message or database segment is
defined as a DLITypeInfo.DOUBLE and retrieved as a Java short. Warnings are
silently chained to the object whose method caused it to be reported.
getNextWarning ()
public DLIWarning getNextWarning()
Get the warning chained to this one.
Returns: The next DLIWarning in the chain, null if none
A.21 Class com.ibm.ims.base.IMSException
java.lang.Object
+----java.lang.Throwable
+----java.lang.Exception
+----com.ibm.ims.base.IMSException
public class IMSException extends Exception
This exception is thrown to indicate a DLI error has ocurred. These include all
errors which result in a non-blank IMS status code and DLI calls resulting in a
Appendix A. IMS Java package 259

Constructor
Methods
non-zero return code for which there s no PCB (and therefore no status
code).
IMSException (String, AIB, short, String)
public IMSException(String function,
AIB aib,
short statCode,
String exceptionType)
Constructor for DLI exceptions.
Parameters:
function - The DLI function.
aib - AIB
statCode - The status code
260 IMS Version 7 and Java Application Programming
exceptionType - The exception description message.
IMSException (String)
public IMSException(String message)
Constructor for exceptions with a message.
Parameters:
message - The message.
IMSException ()
public IMSException()
Constructor for exceptions.
getAIB ()
public AIB getAIB()
Returns the IMS AIB from DLI call which caused this exception.
Returns: AIB.
getFunction ()
public String getFunction()
Returns the IMS function from DLI call which caused this exception.
Returns: Function.

getStatusCode ()
public short getStatusCode()
Returns the IMS status code from DLI call which caused this exception.
Returns: Status code.
A.22 Contents of com.ibm.ims.db package
The com.ibm.ims.db package contains the following Interface Class:
com.ibm.ims.db.DLIParserConstants
The com.ibm.ims.db package contains the following classes:
com.ibm.ims.db.ASCII_UCodeESC_CharStream
com.ibm.ims.db.DLIConnection
com.ibm.ims.db.DLIConnectionTrace
com.ibm.ims.db.DLIDatabaseView
com.ibm.ims.db.DLIDriver
com.ibm.ims.db.DLIParserTokenManager
com.ibm.ims.db.DLIRecord
com.ibm.ims.db.DLISegment
com.ibm.ims.db.DLISegmentInfo
com.ibm.ims.db.DLIStatement
com.ibm.ims.db.DLIStatementTrace
com.ibm.ims.db.IMSErrorMessages
com.ibm.ims.db.SSA
com.ibm.ims.db.SSAList
com.ibm.ims.db.SSAQualificationStatement
com.ibm.ims.db.SSAQualificationStatementTrace
com.ibm.ims.db.Token
The com.ibm.ims.db package contains the following exception classes:
com.ibm.ims.db.DLIException
com.ibm.ims.db.DLISQLException
com.ibm.ims.db.ParseException
The com.ibm.ims.db package contains the following Error handling classes:
com.ibm.ims.db.TokenMgrError
Appendix A. IMS Java package 261

A.23 Class com.ibm.ims.db.DLIConnection
Constructors
Methods
java.lang.Object
+----com.ibm.ims.db.DLIConnection
public class DLIConnection extends Object
A DLIConnection object represents a connection with a DL/I database. It
provides the interface to create DLIStatement objects as well as the interface
to read, write, update, and delete segments in a DL/I database.
DLIConnection (DLIDatabaseView)
protected DLIConnection (DLIDatabaseView dbView)
DLIConnection (String url)
protected DLIConnection (String url)
createInstance (DLIDatabaseView)
public static DLIConnection createInstance(DLIDatabaseView dbView)
Creates a connection with a DL/I database.
Parameters:
dbView - A DLIDatabaseView object.
See Also: DLIDatabaseView.
createInstance (String)
public static DLIConnection createInstance(String url)
Creates a connection with a DL/I database. For example, the following
code fragment creates a database connection
262 IMS Version 7 and Java Application Programming
DLIConnection connection =
DLIConnection.createInstance(“samples.ivp.IVPDatabaseView”);
Parameters:
url - The fully qualified path to a DLIDatabaseView class name.
See Also: DLIDatabaseView.

deleteSegments ()
public void deleteSegments() throws IMSException
Removes a segment and its dependents from the database. This call must
be preceded by either getNextSegment, getNextSegmentInParent, or
getUniqueSegment, as each of these calls get a ‘hold’ on a segment so
that it may be modified in some way.
Throws: IMSException if an error occurs trying to delete the segment.
getAIB ()
public final AIB getAIB()
Returns the Application Interface Block (AIB) used by the connection.
Returns: The Application Interface Block (AIB).
getNextRecord (DLIRecord, SSAList)
public boolean getNextRecord(DLIRecord record,
SSAList ssaList) throws IMSException
Retrieves segments in a path call sequentially from the database. This call
is usually preceded by a getUniqueRecord call, which establishes a starting
position for sequential processing. If not, this call will position at the root of
the entire database.
Parameters:
segment - The DLIRecord that will be populated with the segments
specified by the SSAList parameter.
ssaList - The SSA list specifying the desired DL/I segments in the
path.
Returns: True if there was a record in the database matching the
ssaList, false otherwise.
Throws: IMSException if an error occurs trying to retrieve the record.
getNextSegment (DLISegment, SSAList)
public boolean getNextSegment(DLISegment segment,
SSAList ssaList) throws IMSException
Retrieves a segment sequentially from the database. This call is usually
preceded by a getUniqueSegment call, which establishes a starting position
for sequential processing. If not, this call will position at the root of the
entire database.
Parameters:
Appendix A. IMS Java package 263

264 IMS Version 7 and Java Application Programming
segment - The DL/I segment that will be populated with the segment
specified by the SSAList parameter.
ssaList - The SSA list specifying the desired DL/I segment.
Returns: True if was a segment in the database matching the ssaList,
false otherwise.
Throws: IMSException if an error occurs trying to retrieve the segment.
getNextSegment (SSAList)
public DLISegment getNextSegment(SSAList ssaList) throws IMSException
Retrieves a segment sequentially from the database. This call is usually
preceded by a getUniqueSegment call, which establishes a starting position
for sequential processing. If not, this call will position at the root of the
entire database. To perform an unqualified call, pass in null for the ssaList
parameter.
Parameters:
ssaList - The SSA list specifying the desired DL/I segment, or null if
performing an unqualified call.
Returns: The DLISegment satisfying the SSAList.
Throws:
IMSException if an error occurs trying to retrieve the segment.
DLIException if a segment is returned from the call that is not in the
DLIDatabaseView of the application.
getNextSegmentInParent (DLISegment, SSAList)
public boolean getNextSegmentInParent(DLISegment segment,
SSAList ssaList) throws IMSException
Retrieves a dependent segment sequentially from the database. This call
is usually preceded by a getUniqueSegment call, which establishes a starting
position for sequential processing. If not, this call will position at the root of
the entire database.
Parameters:
segment - The DL/I segment that will be populated with the segment
specified by the SSAList parameter.
ssaList - The SSA list specifying the desired DL/I segment.
Returns: True if was a segment in the database matching the ssaList,
false otherwise.
Throws: IMSException if an error occurs trying to retrieve the segment.

getNextSegmentInParent (SSAList)
public DLISegment getNextSegmentInParent(SSAList ssaList) throws
IMSException
Retrieves a dependent segment sequentially from the database. This call
is usually preceded by a getUniqueSegment call, which establishes a starting
position for sequential processing. If not, this call will position at the root of
the entire database. To perform an unqualified call, pass in null for the
ssaList parameter.
Parameters:
ssaList - The SSA list specifying the desired DL/I segment, or null if
performing an unqualified call.
Returns: True if was a segment in the database matching the ssaList,
false otherwise.
Throws:
IMSException if an error occurs trying to retrieve the segment.
DLIException if a segment is returned from the call that is not in the
DLIDatabaseView of the application.
getUniqueRecord (DLIRecord, SSAList)
public boolean getUniqueRecord(DLIRecord record,
SSAList ssaList) throws IMSException
Directly retrieves the segments in a path from the database and
establishes a starting position in the database for sequential processing.
Parameters:
record - The DLIRecord that will be populated with the segments
specified by the SSAList parameter.
ssaList - The SSA list specifying the desired DL/I leaf segment. The
SSAs in the SSAList should have the PATH_CALL command code
set on each segment to be retrieved. The P processing option must
be specified in the PCB to use this function.
Returns: True if there was a record in the database matching the
ssaList, false otherwise.
Throws: IMSException if an error occurs trying to retrieve the record.
getUniqueSegment (DLISegment, SSAList)
public boolean getUniqueSegment(DLISegment segment,
SSAList ssaList) throws IMSException
Appendix A. IMS Java package 265

Directly retrieves a segment from the database and establishes a starting
position in the database for sequential processing.
Parameters:
266 IMS Version 7 and Java Application Programming
segment - The DL/I segment that will be populated with the segment
specified by the SSAList parameter.
ssaList - The SSA list specifying the desired DL/I segment.
Returns: True if there was a segment in the database matching the
ssaList, false otherwise.
Throws: IMSException if an error occurs trying to retrieve the segment.
getUniqueSegment (SSAList)
public DLISegment getUniqueSegment(SSAList ssaList) throws IMSException
Directly retrieves a segment from the database and establishes a starting
position in the database for sequential processing. To perform an
unqualified call, pass in null for the ssaList parameter.
Parameters:
ssaList - The SSA list specifying the desired DL/I segment, or null if
performing an unqualified call.
Returns: true if there was a segment in the database matching the
ssaList, false otherwise.
Throws:
IMSException if an error occurs trying to retrieve the segment.
DLIException if a segment is returned from the call that is not in the
DLIDatabaseView of the application.
insertSegment (DLISegment, SSAList)
public void insertSegment(DLISegment segment,
SSAList ssaList) throws IMSException
Inserts a segment into the database. The SSAList parameter specifies
where this segment will be inserted.
Parameters:
segment - The segment to be inserted into the database.
ssaList - The SSA list specifying where the segment will be added.
Throws: IMSException if an error occurs trying to insert the segment.

eplaceSegment (DLISegment)
public void replaceSegment(DLISegment segment) throws IMSException
Replaces a segment in the database. This call must be preceded by either
getNextSegment, getNextSegmentInParent, or getUniqueSegment, as each of
these calls get a ‘hold’ on a segment so that it may be modified in some
way.
Parameters:
segment - The segment that will replace the existing segment in the
database that was returned with one of the three hold calls.
Throws: IMSException if an error occurs trying to replace the segment.
A.24 Class com.ibm.ims.db.DLIDatabaseView
java.lang.Object
+----com.ibm.ims.db.DLIDatabaseView
public abstract class DLIDatabaseView extends Object
DLIDatabaseView is a container for segment information in a DL/I database.
During static initialization of a DLIDatabaseView subclass, the subclass should
create an array of DLISegmentInfo objects. The subclass constructor then
provides both the array and the name of the view to the DLIDatabaseView
constructor. DLISegmentInfo contains a DLISegment instance and the 0-based
offset of the parent instance within the array. DLIDatabaseView stores the array
of DLISegmentInfo objects and also creates a Hashtable for fast lookup by
segment class name. Figure 119 shows code typical of a DLIDatabaseView
subclass.
Appendix A. IMS Java package 267

Variables
Methods
class MyDatabaseView extends DLIDatabaseView {
static DLISegmentInfo[] segments = {
new DLISegmentInfo(new RootSegment(), DLIDatabaseView.ROOT),
new DLISegmentInfo(new Seg1(), 0),
new DLISegmentInfo(new Seg2(), 0),
new DLISegmentInfo(new Seg11(), 1),
new DLISegmentInfo(new Seg21(), 2),
new DLISegmentInfo(new Seg211(), 4)
};
public MyDatabaseView ( ) {
super (“DBPCBName”, segments);
}
}
Figure 119. Example: A typical DLIDatabaseView subclass
ROOT
public static final int ROOT
Used to identify that the root segment in a DLIDatabaseView has no parent.
DLIDatabaseView (String, DLISegmentInfo)
protected DLIDatabaseView(String dbPCBName,
DLISegmentInfo segments[])
Constructs a DLIDatabaseView object from the view name and an array of
DLISegmentInfo objects that define the segments contained in the view.
Parameters:
dbPCBName - The name of the database PCB.
segments - The array of segments contained in the view identifying
the segment hierarchy.
Throws: SQLException if a database access error occurs.
A.25 Class com.ibm.ims.db.DLIRecord
java.lang.Object
+----com.ibm.ims.db.DLIRecord
public class DLIRecord extends Object
268 IMS Version 7 and Java Application Programming

Constructor
Method
An object that represents a path of segments Note: This is package level for
now.
DLIRecord (int, int)
public DLIRecord(int segmentCount,int ioAreaLength)
addSegment (DLISegment)
public void addSegment(DLISegment segment)
A.26 Class com.ibm.ims.db.DLISegment
java.lang.Object
+----com.ibm.ims.base.DLIBaseSegment
+----com.ibm.ims.db.DLISegment
public abstract class DLISegment extends DLIBaseSegment
DLISegment is the abstract base class for objects representing segments in a
DL/I database. These DLISegment subclasses provide the mapping between
the data in the segment and access functions on the class. To provide the
mapping, the subclasses must register their DLITypeInfo with this class by
providing it as the argument to the constructor. By doing so, the DLISegment
class knows the layout of each segment in the database and can access as
well as update each of the fields within a segment. Note that when creating
the DLITypeInfo objects to register with a DLISegment the offsets are 1-based.
In the example below, the first paramter is an alias for the key and search
fields. This alias would then be used throughout the application when
referring to the key or search field. The key and search fields are given as the
last paramter and must be defined exactly as they are defined in the DBD
source file. The reason for this is that in the DBD source the field names are
limited to 8 characters, whereas the alias has no such limitations. Figure 120
shows code typical of a DLISegment subclass:
Appendix A. IMS Java package 269

Constructor
Methods
class MySegment extends DLISegment {
static DLITypeInfo[] typeInfo = {
new DLITypeInfo(“FieldAlias1”,DLITypeInfo.CHAR, 1, 6, “Field1”),
new DLITypeInfo(“FieldAlias2”,DLITypeInfo.INTEGER, 7, 4, “Field2”),
new DLITypeInfo(“FieldAlias3”,DLITypeInfo.BIGINT, 11, 8, “Field3”),
};
public MySegment() {
super (“SegmentName”, typeInfo, 18);
}
}
Figure 120. Example: A typical DLISegment subclass
See Also: DLITypeInfo.
DLISegment (String, DLITypeInfo[ ], int)
protected DLISegment(String segmentName,DLITypeInfo typeInfo[],int length)
Constructs a DL/I Segment object. By providing an array of DLITypeInfo
objects as an argument, this class knows the layout of the segment and
can access as well as update each field within the segment.
Parameters:
270 IMS Version 7 and Java Application Programming
segmentName - The name of the segment in the database.
typeInfo - An array of DLITypeInfo objects, which tells this class the
layout of the segment.
length - The length of the I/O area of the segment.
clearWarnings ()
public void clearWarnings()
Clears the warning chain for this DLISegment. After this call getWarnings
returns null until a new warning is reported for this DLISegment.
Overrides: clearWarnings in class DLIBaseSegment.
getWarnings ()
public DLIWarning getWarnings()
The first warning reported by calls on this DLISegment is returned.
Subsequent warnings will be chained to this DLIWarning. The warning chain

is automatically cleared each time a new segment is read from the
database.
Returns: The first DLIWarning or null.
Overrides: getWarnings in class DLIBaseSegment.
A.27 Class com.ibm.ims.db.DLISegmentInfo
Constructor
Note:
This warning chain only covers warnings caused by DLISegment
methods.
java.lang.Object
+----com.ibm.ims.db.DLISegmentInfo
public final class DLISegmentInfo extends Object
A DLISegmentInfo object is wrapper class used to associate a DLISegment
object with its hierarchical parent for use within a DLIDatabaseView object.
Subclasses of DLIDatabaseView statically create an array of DLISegmentInfo
objects and pass the array to the DLIDatabaseView constructor.
DLISegmentInfo (DLISegment, int)
public DLISegmentInfo(DLISegment segment,int parentIndex)
Constructs a DLISegmentInfo object from an instance of a DLISegment and
the index of the hierarchical parent in an array of DLISegmentInfo objects.
Parameters:
segment - A DLISegment object.
parentIndex - The index of the parent’s DLISegmentInfo object in an
array of DLISegmentInfo objects.
A.28 Class com.ibm.ims.db.DLIStatement
java.lang.Object
+----com.ibm.ims.db.DLIStatement
Appendix A. IMS Java package 271

Methods
public class DLIStatement extends Object implements Statement
The object used for executing a static SQL statement and obtaining the
results produced by it. Only one ResultSet per Statement can be open at any
point in time. Therefore, if the reading of one ResultSet is interleaved with the
reading of another, each must have been generated by different Statements.
All statement execute methods implicitly close a statment's current ResultSet
if an open one exists.
See Also: createStatement, ResultSet.
executeQuery (String)
public ResultSet executeQuery(String sql) throws SQLException
Executes a SQL statement that returns a single ResultSet.
Parameters:
sql - Typically this is a static SQL SELECT statement.
Returns: A ResultSet that contains the data produced by the query;
never null.
Throws: SQLException if a database access error occurs.
executeQuery (DLIParser)
protected ResultSet executeQuery(DLIParser parser) throws SQLException
executeUpdate (String)
public int executeUpdate(String sql) throws SQLException
Executes an SQL INSERT, UPDATE or DELETE statement. In addition, SQL
statements that return nothing, such as SQL DDL statements, can be
executed.
Parameters:
sql - A SQL INSERT, UPDATE or DELETE statement or a SQL statement
that returns nothing.
Returns: Either the row count for INSERT, UPDATE or DELETE or 0 for SQL
statements that return nothing.
Throws: SQLException if a database access error occurs.
272 IMS Version 7 and Java Application Programming

executeUpdate (DLIParser)
protected int executeUpdate(DLIParser parser) throws SQLException
close ()
public void close() throws SQLException
Releases this Statement object's database and JDBC resources
immediately instead of waiting for this to happen when it is automatically
closed. It is generally good practice to release resources as soon as you
are finished with them to avoid tying up database resources.
Note
Note: A Statement is automatically closed when it is garbage collected.
When a Statement is closed, its current ResultSet, if one exists, is also
closed.
Throws: SQLException if a database access error occurs.
getMaxFieldSize ()
public int getMaxFieldSize() throws SQLException
Returns the maximum number of bytes allowed for any column value. This
limit is the maximum number of bytes that can be returned for any column
value. The limit applies only to BINARY, VARBINARY, LONGVARBINARY, CHAR,
VARCHAR, and LONGVARCHAR columns. If the limit is exceeded, the excess data
is silently discarded.
Returns: The current max column size limit; zero means unlimited.
Throws: SQLException if a database access error occurs.
setMaxFieldSize (int)
public void setMaxFieldSize(int max) throws SQLException
Sets the limit for the maximum number of bytes in a column to the given
number of bytes. This is the maximum number of bytes that can be
returned for any column value. This limit applies only to BINARY, VARBINARY,
LONGVARBINARY, CHAR, VARCHAR, and LONGVARCHAR fields. If the limit is exceeded,
the excess data is silently discarded. For maximum portability, use values
greater than 256.
Parameters:
max - The new max column size limit; zero means unlimited.
Throws: SQLException if a database access error occurs.
Appendix A. IMS Java package 273

getMaxRows ()
public int getMaxRows() throws SQLException
Retrieves the maximum number of rows that a ResultSet can contain. If the
limit is exceeded, the excess rows are silently dropped.
Returns: The current max row limit; zero means unlimited.
Throws: SQLException if a database access error occurs.
setMaxRows (int)
public void setMaxRows(int max) throws SQLException
Sets the limit for the maximum number of rows that any ResultSet can
contain to the given number. If the limit is exceeded, the excess rows are
silently dropped.
Parameters:
max - The new max rows limit; zero means unlimited.
Throws: SQLException if a database access error occurs.
setEscapeProcessing (boolean)
public void setEscapeProcessing(boolean enable) throws SQLException
Sets escape processing on or off. If escape scanning is on (the default),
the driver will do escape substitution before sending the SQL to the
database.
Note
Since prepared statements have usually been parsed prior to making
this call, disabling escape processing for prepared statements will have
no effect.
Parameters:
enable - True to enable; false to disable.
Throws: SQLException if a database access error occurs.
getQueryTimeout ()
public int getQueryTimeout() throws SQLException
Retrieves the number of seconds the driver will wait for a Statement to
execute. If the limit is exceeded, a SQLException is thrown.
Returns: The current query timeout limit in seconds; zero means
unlimited.
274 IMS Version 7 and Java Application Programming

Throws: SQLException if a database access error occurs.
setQueryTimeout (int)
public void setQueryTimeout(int seconds) throws SQLException
Sets the number of seconds the driver will wait for a Statement to execute
to the given number of seconds. If the limit is exceeded, a SQLException
is thrown.
Parameters:
seconds - The new query timeout limit in seconds; zero means
unlimited.
Throws: SQLException if a database access error occurs.
cancel ()
public void cancel() throws SQLException
Cancels this Statement object if both the DBMS and driver support aborting
an SQL statement. This method can be used by one thread to cancel a
statement that is being executed by another thread.
Throws: SQLException if a database access error occurs.
getWarnings ()
public SQLWarning getWarnings() throws SQLException
Retrieves the first warning reported by calls on this Statement.
Subsequent Statement warnings will be chained to this SQLWarning. The
warning chain is automatically cleared each time a statement is
(re)executed.
Note:
If you are processing a ResultSet, any warnings associated with
ResultSet reads will be chained on the ResultSet object.
Returns: the first SQLWarning or null.
Throws: SQLException if a database access error occurs.
clearWarnings ()
public void clearWarnings() throws SQLException
Clears all the warnings reported on this Statement object. After a call to
this method, the method getWarnings will return null until a new warning is
reported for this Statement.
Appendix A. IMS Java package 275

Throws: SQLException if a database access error occurs.
setCursorName (String)
public void setCursorName(String name) throws SQLException
Defines the SQL cursor name that will be used by subsequent Statement
execute methods. This name can then be used in SQL positioned
update/delete statements to identify the current row in the ResultSet
generated by this statement. If the database doesn't support positioned
update/delete, this method is a noop. To insure that a cursor has the
proper isolation level to support updates, the cursor's SELECT statement
should be of the form 'select for update ...'. If the 'for update' phrase is
omitted, positioned updates may fail.
Note
By definition, positioned update/delete execution must be done by a
different Statement than the one which generated the ResultSet being
used for positioning. Also, cursor names must be unique within a
connection.
Parameters:
name - The new cursor name, which must be unique within a
connection.
Throws: SQLException if a database access error occurs.
execute (String)
public boolean execute(String sql) throws SQLException
Executes a SQL statement that may return multiple results. Under some
(uncommon) situations a single SQL statement may return multiple result
sets and/or update counts. Normally you can ignore this unless you are (1)
executing a stored procedure that you know may return multiple results or
(2) you are dynamically executing an unknown SQL string. The methods
execute, getMoreResults, getResultSet, and getUpdateCount let you navigate
through multiple results. The execute method executes a SQL statement
and indicates the form of the first result. You can then use getResultSet or
getUpdateCount to retrieve the result, and getMoreResults to move to any
subsequent result(s).
Parameters:
sql - Any SQL statement.
276 IMS Version 7 and Java Application Programming

Returns: true if the next result is a ResultSet; false if it is an update
count or there are no more results.
Throws: SQLException if a database access error occurs.
See Also: getResultSet, getUpdateCount, getMoreResults.
execute (DLIParser)
protected boolean execute(DLIParser parser) throws SQLException
getResultSet ()
public ResultSet getResultSet() throws SQLException
Returns the current result as a ResultSet object. This method should be
called only once per result.
Returns: The current result as a ResultSet; null if the result is an
update count or there are no more results.
Throws: SQLException if a database access error occurs.
See Also: execute.
getUpdateCount ()
public int getUpdateCount() throws SQLException
Returns the current result as an update count; if the result is a ResultSet
or there are no more results, -1 is returned. This method should be called
only once per result.
Returns: the current result as an update count; -1 if it is a ResultSet or
there are no more results.
Throws: SQLException if a database access error occurs.
See Also: execute.
getMoreResults ()
public boolean getMoreResults() throws SQLException
Moves to a Statement's next result. It returns true if this result is a
ResultSet. This method also implicitly closes any current ResultSet
obtained with getResultSet. There are no more results when
(!getMoreResults() && (getUpdateCount() == -1).
Returns: True if the next result is a ResultSet; false if it is an update
count or there are no more results.
Throws: SQLException if a database access error occurs.
See Also: execute.
Appendix A. IMS Java package 277

setFetchDirection (int)
public void setFetchDirection(int direction) throws SQLException
JDBC 2.0 Gives the driver a hint as to the direction in which the rows in a
result set will be processed. The hint applies only to result sets created
using this Statement object. The default value is ResultSet.FETCH_FORWARD.
Note that this method sets the default fetch direction for result sets
generated by this Statement object. Each result set has its own methods
for getting and setting its own fetch direction.
Parameters:
direction - The initial direction for processing rows.
Throws: SQLException if a database access error occurs or the given
direction is not one of ResultSet.FETCH_FORWARD,
ResultSet.FETCH_REVERSE, or ResultSet.FETCH_UNKNOWN.
getFetchDirection ()
public int getFetchDirection() throws SQLException
JDBC 2.0 Retrieves the direction for fetching rows from database tables
that is the default for result sets generated from this Statement object. If
this Statement object has not set a fetch direction by calling the method
setFetchDirection, the return value is implementation-specific.
Returns: the default fetch direction for result sets generated from this
Statement object.
Throws: SQLException if a database access error occurs.
setFetchSize (int)
public void setFetchSize(int rows) throws SQLException
JDBC 2.0 Gives the JDBC driver a hint as to the number of rows that
should be fetched from the database when more rows are needed. The
number of rows specified affects only result sets created using this
statement. If the value specified is zero, then the hint is ignored. The
default value is zero.
Parameters:
rows - The number of rows to fetch.
Throws: SQLException if a database access error occurs, or the
condition 0

JDBC 2.0 Retrieves the number of result set rows that is the default fetch
size for result sets generated from this Statement object. If this Statement
object has not set a fetch size by calling the method setFetchSize, the
return value is implementation-specific.
Returns: The default fetch size for result sets generated from this
Statement object.
Throws: SQLException if a database access error occurs.
A.29 Class com.ibm.ims.db.IMSErrorMessages
Constructor
Methods
java.lang.Object
+----java.util.ResourceBundle
+----java.util.ListResourceBundle
+----com.ibm.ims.db.IMSErrorMessages
public class IMSErrorMessages extends ListResourceBundle
IMSErrorMessages ()
public IMSErrorMessages()
Creates a resource bundle for giving error messages.
getContents ()
protected Object[ ][ ] getContents()
getContents method comment.
Overrides: getContents in class ListResourceBundle.
getIMSBundle ()
public static IMSErrorMessages getIMSBundle()
Returns the translated resource bundle.
Returns: com.ibm.ims.db.IMSErrorMessages.
getString (String, Object)
public String getString(String key,
Object inserts[ ])
Parameters:
Appendix A. IMS Java package 279

key - java.lang.String.
inserts - java.lang.Object[ ].
Returns: java.lang.String.
A.30 Class com.ibm.ims.db.SSA
Variables
java.lang.Object
+----com.ibm.ims.db.SSA
public class SSA extends Object
EQUALS
public static final short EQUALS
Relational operator for equals (=).
GREATER_OR_EQUAL
public static final short GREATER_OR_EQUAL
Relational operator for greater than or equal to (>=).
LESS_OR_EQUAL
public static final short LESS_OR_EQUAL
Relational operator for less than or equal to ().
LESS_THAN
public static final short LESS_THAN
Relational operator for less than (

Boolean operator AND.
OR
public static final byte OR
Boolean operator OR.
INDEPENDENT_AND
public static final byte INDEPENDENT_AND
Boolean operator INDEPENDENT AND.
NULL_COMMAND
public static final byte NULL_COMMAND
Command code meaning null command code (ignored).
CONCATENATED_KEY
public static final byte CONCATENATED_KEY
Command code meaning concatenated key.
PATH_CALL
public static final byte PATH_CALL
FIRST_OCCURRENCE
public static final byte FIRST_OCCURRENCE
Command code meaning first occurrence.
LAST_OCCURRENCE
public static final byte LAST_OCCURRENCE
Command code meaning last occurrence.
PATH_CALL_IGNORE
public static final byte PATH_CALL_IGNORE
Command code meaning path call ignore.
SET_PARENTAGE
public static final byte SET_PARENTAGE
Command code meaning set parentage.
ENQUEUE_SEGMENT
public static final byte ENQUEUE_SEGMENT
Command code meaning enqueue segment.
Appendix A. IMS Java package 281

MAINTAIN_POS_AT_LEVEL
public static final byte MAINTAIN_POS_AT_LEVEL
Command code meaning maintain position at this level.
MAINTAIN_POS_AT_SUPERIOR_LEVELS
public static final byte MAINTAIN_POS_AT_SUPERIOR_LEVELS
Command code meaning maintain position at this level and all superior
levels.
LOCK_CLASS_A
public static final byte LOCK_CLASS_A
Code designating the lock class of a segment (for use with command code
Q).
LOCK_CLASS_B
public static final byte LOCK_CLASS_B
Code designating the lock class of a segment (for use with command code
Q).
LOCK_CLASS_C
public static final byte LOCK_CLASS_C
Code designating the lock class of a segment (for use with command code
Q).
LOCK_CLASS_D
public static final byte LOCK_CLASS_D
Code designating the lock class of a segment (for use with command code
Q).
LOCK_CLASS_E
public static final byte LOCK_CLASS_E
Code designating the lock class of a segment (for use with command code
Q).
LOCK_CLASS_F
public static final byte LOCK_CLASS_F
Code designating the lock class of a segment (for use with command code
Q).
282 IMS Version 7 and Java Application Programming

Constructors
LOCK_CLASS_G
public static final byte LOCK_CLASS_G
Code designating the lock class of a segment (for use with command code
Q).
LOCK_CLASS_H
public static final byte LOCK_CLASS_H
Code designating the lock class of a segment (for use with command code
Q).
LOCK_CLASS_I
public static final byte LOCK_CLASS_I
Code designating the lock class of a segment (for use with command code
Q).
LOCK_CLASS_J
public static final byte LOCK_CLASS_J
Code designating the lock class of a segment (for use with command code
Q).
SSA (String)
protected SSA(String segmentClassName)
Protected constructor to create an unqualified SAA.
Parameters:
segmentClassName - the class name of the DLISegment subclass.
SSA (String, String, short, String)
protected SSA(String segmentClassName,
String fieldName,
short ssaRelationalOperator,String comparisonValue)
Package constructor to create a qualified SAA.
Parameters:
segmentClassName - The class name of the DLISegment subclass.
fieldName - The field name to be used to further qualify the SSA.
ssaRelationalOperator - The relational operator to indicate the kind
of checking.
Appendix A. IMS Java package 283

Methods
284 IMS Version 7 and Java Application Programming
comparisonValue - The value the field name is compared with.
addCommandCode (byte)
public void addCommandCode(byte ssaCommandCode)
Adds a command code to an SSA. The SSA class defines several
constants that can be supplied as values for the ssaCommandCode argument:
NULL_COMMAND, CONCATENATED_KEY, FIRST_OCCURRENCE, LAST_OCCURRENCE,
PATH_CALL, PATH_CALL_IGNORE, SET_PARENTAGE, MAINTAIN_POS_AT_LEVEL, and
MAINTAIN_POS_AT_SUPERIOR_LEVELS.
Parameters:
ssaCommandCode - A constant to indicate the function to execute.
addCommandCode (byte, byte)
public void addCommandCode(byte ssaCommandCode,byte lockClass)
Adds a command code to an SSA. This method is used to specify a lock
class for a segment. The SSA class defines the constant ENQUEUE_SEGMENT to
be supplied as the value for the ssaCommandCode argument. The following
codes are provided to specify the lock class for the segment: LOCK_CLASS_A,
LOCK_CLASS_B, LOCK_CLASS_C, LOCK_CLASS_D, LOCK_CLASS_E, LOCK_CLASS_F,
LOCK_CLASS_G, LOCK_CLASS_H, LOCK_CLASS_I, and LOCK_CLASS_J..
Parameters:
ssaCommandCode - A constant to indicate the function to execute.
addQualificationStatement (byte, String, short, String)
public void addQualificationStatement(byte ssaBooleanOperator,
String fieldName,
short ssaRelationalOperator,
String comparisonValue) throws
DLIException
Adds a qualification statement to an SSA. To indicate that a comparison
value may be changed at a later time, pass a null reference for the value.
When using the SSA, call the setValue(int index, String value) method in
SSAList to substitute in the desired value. The SSA class defines several
constants that can be supplied as values for the ssaBooleanOperator
argument: AND, OR, and INDEPENDENT_AND. The SSA class defines several
constants that can be supplied as values for the ssaRelationalOperator
argument: EQUALS, GREATER_OR_EQUAL, LESS_OR_EQUAL, GREATER_THAN,
LESS_THAN, and NOT_EQUAL.

Parameters:
ssaBooleanOperator - A constant to link qualifications together in
SSAs with multiple qualifications.
fieldName - The field name to be used to further qualify the SSA.
ssaRelationalOperator - A constant to indicate the kind of checking.
comparisonValue - The value the field name is compared with.
Throws: DLIException if the SSA is formed incorrectly (the first
qualification statement added is a multiple qualification statement).
See Also: setValue.
addQualificationStatement (SSAQualificationStatement)
public void addQualificationStatement(SSAQualificationStatement
ssaQualificationStatement) throws DLIException
Adds a qualification statement specified by the ssaQualificationStatement
argument to an SSA.
Parameters:
ssaQualificationStatement - An SSA qualification statement.
Throws: DLIException if the SSA is formed incorrectly (the first
qualification statement added is a multiple qualification statement).
addQualificationStatement (String, short, String)
public void addQualificationStatement(String fieldName,
short ssaRelationalOperator,
String comparisonValue) throws
DLIException
Adds a qualification statement to an SSA. To indicate that a comparison
value may be changed at a later time, pass a null reference for the value.
When using the SSA, call the setValue(int index, String value) method in
SSAList to substitute in the desired value. The SSA class defines several
constants that can be supplied as values for the ssaBooleanOperator
argument: AND, OR, and INDEPENDENT_AND. The SSA class defines several
constants that can be supplied as values for the ssaRelationalOperator
argument: EQUALS, GREATER_OR_EQUAL, LESS_OR_EQUAL, GREATER_THAN,
LESS_THAN, and NOT_EQUAL.
Parameters:
fieldName - The field name to be used to further qualify the SSA.
ssaRelationalOperator - A constant to indicate the kind of checking.
Appendix A. IMS Java package 285

comparisonValue - The value the field name is compared with.
Throws: DLIException if the SSA is formed incorrectly (the first
qualification statement added is a multiple qualification statement).
See Also: setValue.
createInstance (String)
public static SSA createInstance(String segmentClassName)
Creates an unqualified SSA. Qualification statements may be added to
this SSA to qualify it.
Parameters:
286 IMS Version 7 and Java Application Programming
segmentClassName - The class name of the DLISegment subclass.
createInstance (String, String, short, String)
public static SSA createInstance(String segmentClassName,
String fieldName,
short ssaRelationalOperator,
String comparisonValue)
Creates a qualified SSA. More qualification statements may also be
added. To indicate that a comparison value may be changed at a later
time, pass a null reference for the value. When using the SSA, call one of
the overloaded setValue() methods of the SSAList class to substitute in the
desired value.
Parameters:
segmentClassName - The class name of the DLISegment subclass.
fieldName - The field name to be used to further qualify the SSA.
ssaRelationalOperator - The relational operator to indicate the kind
of checking.
comparisonValue - The value the field name is compared with.
See Also: setValue, setValue, setValue, setValue, setValue, setValue,
setValue.
getBytes (DLIDatabaseView)
public byte[ ] getBytes(DLIDatabaseView dbView) throws DLIException
Returns the SSA in EBCDIC exactly as IMS needs it to be.
Returns: a byte array specifying the entire SSA in EBCDIC.
resetCommandCodes ()
public void resetCommandCodes()

Turns off all command codes for this SSA.
A.31 Class com.ibm.ims.db.SSAList
Constructors
Methods
java.lang.Object
+----com.ibm.ims.db.SSAList
public class SSAList extends Object
SSAList ()
protected SSAList()
Creates an SSA list.
SSAList (SSA)
protected SSAList(SSA ssa)
Creates an SSA list from an existing SSA, and places the ssa argument at
the head of the list.
Parameters:
ssa - An SSA.
addSSA (SSA)
public void addSSA(SSA ssa) throws IMSException
Adds the ssa argument to an existing SSA list, placing it at the end of the
list.
Parameters:
ssa - An SSA.
clearParameters ()
public void clearParameters()
createInstance ()
public static SSAList createInstance()
Creates an SSA list.
Appendix A. IMS Java package 287

createInstance (SSA)
public static SSAList createInstance(SSA ssa)
Creates an SSA list from an existing SSA, and places the ssa argument at
the head of the list.
Parameters:
ssa - An SSA.
getBytes (DLIDatabaseView)
public byte[ ][ ] getBytes(DLIDatabaseView dbView) throws IMSException
Returns the SSA list in a two-dimensional byte array. Each element in the
array is an SSA in its EBCDIC format exactly as IMS needs it to be.
Returns: A two-dimensional byte array containing all the SSAs in their
EBCDIC format.
Throws: DLIException if the SSAList does not have all its fields set (i.e.;
some fields still have ‘null’ as their value).
setValue (int, byte)
public void setValue(int index,byte value[])
Sets the value of a prepared parameter to the desired value. A prepared
parameter is one whose value was set to null when the SSA or the
SSAQualificationStatement was created, indicating that the value could be
substituted in later. If an SSAList is composed of 2 SSAs, each with 2
prepared parameters, then the index can be between 1 and 4, inclusive.
For example, an index of 2 would specify the second prepared parameter
of the first SSA in the SSAList.
Parameters:
288 IMS Version 7 and Java Application Programming
index - The index of the parameter value to be changed, starting
with 1.
value - The value of the parameter.
See Also: SSA, SSAQualificationStatement.
setValue (int, byte)
public void setValue(int index,byte value)
Sets the value of a prepared parameter to the desired value. A prepared
parameter is one whose value was set to null when the SSA or the
SSAQualificationStatement was created, indicating that the value could be
substituted in later. If an SSAList is composed of 2 SSAs, each with 2
prepared parameters, then the index can be between 1 and 4, inclusive.

For example, an index of 2 would specify the second prepared parameter
of the first SSA in the SSAList.
Parameters:
index - The index of the parameter value to be changed, starting
with 1.
value - The value of the parameter.
See Also: SSA, SSAQualificationStatement.
setValue (int, double)
public void setValue(int index,double value)
Sets the value of a prepared parameter to the desired value. A prepared
parameter is one whose value was set to null when the SSA or the
SSAQualificationStatement was created, indicating that the value could be
substituted in later. If an SSAList is composed of 2 SSAs, each with 2
prepared parameters, then the index can be between 1 and 4, inclusive.
For example, an index of 2 would specify the second prepared parameter
of the first SSA in the SSAList.
Parameters:
index - The index of the parameter value to be changed, starting
with 1.
value - The value of the parameter.
See Also: SSA, SSAQualificationStatement.
setValue (int, float)
public void setValue(int index,float value)
Sets the value of a prepared parameter to the desired value. A prepared
parameter is one whose value was set to null when the SSA or the
SSAQualificationStatement was created, indicating that the value could be
substituted in later. If an SSAList is composed of 2 SSAs, each with 2
prepared parameters, then the index can be between 1 and 4, inclusive. For
example, an index of 2 would specify the second prepared parameter of the
first SSA in the SSAList.
Parameters:
index - The index of the parameter value to be changed, starting
with 1.
value - The value of the parameter.
See Also: SSA, SSAQualificationStatement.
Appendix A. IMS Java package 289

setValue (int, int)
public void setValue(int index,int value)
Sets the value of a prepared parameter to the desired value. A prepared
parameter is one whose value was set to null when the SSA or the
SSAQualificationStatement was created, indicating that the value could be
substituted in later. If an SSAList is composed of 2 SSAs, each with 2
prepared parameters, then the index can be between 1 and 4, inclusive.
For example, an index of 2 would specify the second prepared parameter
of the first SSA in the SSAList.
Parameters:
290 IMS Version 7 and Java Application Programming
index - The index of the parameter value to be changed, starting
with 1.
value - The value of the parameter.
See Also: SSA, SSAQualificationStatement.
setValue (int, long)
public void setValue(int index,long value)
Sets the value of a prepared parameter to the desired value. A prepared
parameter is one whose value was set to null when the SSA or the
SSAQualificationStatement was created, indicating that the value could be
substituted in later. If an SSAList is composed of 2 SSAs, each with 2
prepared parameters, then the index can be between 1 and 4, inclusive.
For example, an index of 2 would specify the second prepared parameter
of the first SSA in the SSAList.
Parameters:
index - The index of the parameter value to be changed, starting
with 1.
value - The value of the parameter.
See Also: SSA, SSAQualificationStatement.
setValue (int, String)
public void setValue(int index,String value)
Sets the value of a prepared parameter to the desired value. A prepared
parameter is one whose value was set to null when the SSA or the
SSAQualificationStatement was created, indicating that the value could be
substituted in later. If an SSAList is composed of 2 SSAs, each with 2
prepared parameters, then the index can be between 1 and 4, inclusive.

For example, an index of 2 would specify the second prepared parameter
of the first SSA in the SSAList.
Parameters:
index - The index of the parameter value to be changed, starting
with 1.
value - The value of the parameter, which will be converted to its
appropriate type as defined in the type info.
See Also: SSA, SSAQualificationStatement.
setValue (int, BigDecimal)
public void setValue(int index,BigDecimal value)
Sets the value of a prepared parameter to the desired value. A prepared
parameter is one whose value was set to null when the SSA or the
SSAQualificationStatement was created, indicating that the value could be
substituted in later. If an SSAList is composed of 2 SSAs, each with 2
prepared parameters, then the index can be between 1 and 4, inclusive.
For example, an index of 2 would specify the second prepared parameter
of the first SSA in the SSAList.
Parameters:
index - The index of the parameter value to be changed, starting
with 1.
value - The value of the parameter.
See Also: SSA, SSAQualificationStatement.
setValue (int, Date)
public void setValue(int index,Date value)
Sets the value of a prepared parameter to the desired value. A prepared
parameter is one whose value was set to null when the SSA or the
SSAQualificationStatement was created, indicating that the value could be
substituted in later. If an SSAList is composed of 2 SSAs, each with 2
prepared parameters, then the index can be between 1 and 4, inclusive.
For example, an index of 2 would specify the second prepared parameter
of the first SSA in the SSAList.
Parameters:
index - The index of the parameter value to be changed, starting
with 1.
value - The value of the parameter.
Appendix A. IMS Java package 291

See Also: SSA, SSAQualificationStatement.
setValue (int, Time)
public void setValue(int index,
Time value)
Sets the value of a prepared parameter to the desired value. A prepared
parameter is one whose value was set to null when the SSA or the
SSAQualificationStatement was created, indicating that the value could be
substituted in later. If an SSAList is composed of 2 SSAs, each with 2
prepared parameters, then the index can be between 1 and 4, inclusive.
For example, an index of 2 would specify the second prepared parameter
of the first SSA in the SSAList.
Parameters:
292 IMS Version 7 and Java Application Programming
index - The index of the parameter value to be changed, starting
with 1.
value - The value of the parameter.
See Also: SSA, SSAQualificationStatement.
setValue (int, Timestamp)
public void setValue(int index,
Timestamp value)
Sets the value of a prepared parameter to the desired value. A prepared
parameter is one whose value was set to null when the SSA or the
SSAQualificationStatement was created, indicating that the value could be
substituted in later. If an SSAList is composed of 2 SSAs, each with 2
prepared parameters, then the index can be between 1 and 4, inclusive.
For example, an index of 2 would specify the second prepared parameter
of the first SSA in the SSAList.
Parameters:
index - The index of the parameter value to be changed, starting
with 1.
value - The value of the parameter.
See Also: SSA, SSAQualificationStatement.
setValue (int, short)
public void setValue(int index,short value)
Sets the value of a prepared parameter to the desired value. A prepared
parameter is one whose value was set to null when the SSA or the
SSAQualificationStatement was created, indicating that the value could be

substituted in later. If an SSAList is composed of 2 SSAs, each with 2
prepared parameters, then the index can be between 1 and 4, inclusive.
For example, an index of 2 would specify the second prepared parameter
of the first SSA in the SSAList.
Parameters:
index - The index of the parameter value to be changed, starting
with 1.
value - The value of the parameter.
See Also: SSA, SSAQualificationStatement.
setValue (int, boolean)
public void setValue(int index,boolean value)
Sets the value of a prepared parameter to the desired value. A prepared
parameter is one whose value was set to null when the SSA or the
SSAQualificationStatement was created, indicating that the value could be
substituted in later. If an SSAList is composed of 2 SSAs, each with 2
prepared parameters, then the index can be between 1 and 4, inclusive.
For example, an index of 2 would specify the second prepared parameter
of the first SSA in the SSAList.
Parameters:
index - The index of the parameter value to be changed, starting with 1.
value - The value of the parameter.
See Also: SSA, SSAQualificationStatement.
size ()
public final int size()
Returns the number of SSAs in this list
Returns: The number of SSAs in this list.
ssaAt (int)
public final SSA ssaAt(int index)
Returns the SSA at the specified index.
Parameters:
index - The 1-based index into the list (i.e.; index 1 is the first SSA).
Returns: the SSA at the specified index.
Appendix A. IMS Java package 293

A.32 Class com.ibm.ims.db.SSAQualificationStatement
Constructors
Methods
java.lang.Object
+----com.ibm.ims.db.SSAQualificationStatement
public class SSAQualificationStatement extends Object
A SSAQualificationStatement represents logical qualification statements to a
Segment Search Argument.
SSAQualificationStatement (byte, String, short, String)
protected SSAQualificationStatement(byte ssaBooleanOperator,
String fieldName,
short ssaRelationalOperator,
String comparisonValue)
Protected constructor to build an SSAQualificationStatement.
Parameters:
294 IMS Version 7 and Java Application Programming
ssaBooleanOperator - A constant to link qualifications together in
SSAs with multiple qualifications.
fieldName - The field name to be used to further qualify the SSA.
ssaRelationalOperator - A constant to indicate the kind of checking.
comparisonValue - The value the field name is compared with.
SSAQualificationStatement (String, short, String)
protected SSAQualificationStatement(String fieldName,
short ssaRelationalOperator,
String comparisonValue)
Protected constructor to build an SSAQualificationStatement.
Parameters:
fieldName - The field name to be used to further qualify the SSA.
ssaRelationalOperator - A constant to indicate the kind of checking.
comparisonValue - The value the field name is compared with.
createInstance (byte, String, short)
public static SSAQualificationStatement createInstance(

yte ssaBooleanOperator,
String fieldName,
short ssaRelationalOperator)
This creates an SSA Qualification Statement, which is used to further
qualify a Segment Search Argument. This constructor is used to indicate
that the comparison value will be set later using one of the overloaded
setValue() methods of the SSAList class. The SSA class defines several
constants that can be supplied as values for the ssaBooleanOperator
argument: AND, OR, and INDEPENDENT_AND. The SSA class defines several
constants that can be supplied as values for the ssaRelationalOperator
argument: EQUALS, GREATER_OR_EQUAL, LESS_OR_EQUAL, GREATER_THAN,
LESS_THAN, and NOT_EQUAL.
Parameters:
ssaBooleanOperator - A constant to link qualifications together in
SSAs with multiple qualifications.
fieldName - The field name to be used to further qualify the SSA.
ssaRelationalOperator - A constant to indicate the kind of checking.
See Also: setValue.
createInstance (byte, String, short, String)
public static SSAQualificationStatement createInstance(
byte ssaBooleanOperator,
String fieldName,
short ssaRelationalOperator,
String comparisonValue)
This creates an SSA Qualification Statement, which is used to further
qualify a Segment Search Argument. To indicate that a comparison value
may be changed at a later time, pass a null reference for the value. When
using the SSA, call the overloaded setValue() methods in the SSAList
class to substitute in the desired value. The SSA class defines several
constants that can be supplied as values for the ssaBooleanOperator
argument: AND, OR, and INDEPENDENT_AND. The SSA class defines several
constants that can be supplied as values for the ssaRelationalOperator
argument: EQUALS, GREATER_OR_EQUAL, LESS_OR_EQUAL, GREATER_THAN,
LESS_THAN, and NOT_EQUAL.
Parameters:
ssaBooleanOperator - A constant to link qualifications together in
SSAs with multiple qualifications.
fieldName - The field name to be used to further qualify the SSA.
Appendix A. IMS Java package 295

296 IMS Version 7 and Java Application Programming
ssaRelationalOperator - A constant to indicate the kind of checking.
comparisonValue - The value the field name is compared with.
See Also: setValue.
createInstance (String, short)
public static SSAQualificationStatement createInstance(
String fieldName,
short ssaRelationalOperator)
This creates an SSA Qualification Statement, which is used to further
qualify a Segment Search Argument. This constructor is used to indicate
that the comparison value will be set later using one of the overloaded
setValue() methods of the SSAList class. The SSA class defines several
constants that can be supplied as values for the ssaRelationalOperator
argument: EQUALS, GREATER_OR_EQUAL, LESS_OR_EQUAL, GREATER_THAN,
LESS_THAN, and NOT_EQUAL.
Parameters:
fieldName - The field name to be used to further qualify the SSA.
ssaRelationalOperator - A constant to indicate the kind of checking.
comparisonValue - The value the field name is compared with.
See Also: setValue.
createInstance (String, short, String)
public static SSAQualificationStatement createInstance(
String fieldName,
short ssaRelationalOperator,
String comparisonValue)
This creates an SSA Qualification Statement, which is used to further
qualify a Segment Search Argument. To indicate that a comparison value
may be changed at a later time, pass a null reference for the value. When
using the SSA, call the overloaded setValue() methods in the SSAList
class to substitute in the desired value.
The SSA class defines several constants that can be supplied as values for
the ssaRelationalOperator argument: EQUALS, GREATER_OR_EQUAL,
LESS_OR_EQUAL, GREATER_THAN, LESS_THAN, and NOT_EQUAL.
Parameters:
fieldName - The field name to be used to further qualify the SSA.
ssaRelationalOperator - A constant to indicate the kind of checking.
comparisonValue - The value the field name is compared with.

See Also: setValue.
A.33 Class com.ibm.ims.db.Token
Variables
java.lang.Object
+----com.ibm.ims.db.Token
public class Token extends Object
Describes the input token stream.
beginLine
public int beginLine
beginLine and beginColumn describe the position of the first character of this
token; endLine and endColumn describe the position of the last character
of this token.
beginColumn
public int beginColumn
beginLine and beginColumn describe the position of the first character of this
token; endLine and endColumn describe the position of the last character of
this token.
endLine
public int endLine
beginLine and beginColumn describe the position of the first character of this
token; endLine and endColumn describe the position of the last character of
this token.
endColumn
public int endColumn
beginLine and beginColumn describe the position of the first character of this
token; endLine and endColumn describe the position of the last character of
this token.
image
public String image
The string image of the token.
Appendix A. IMS Java package 297

Constructors
Methods
next
public Token next
A reference to the next regular (non-special) token from the input stream.
If this is the last token from the input stream, or if the token manager has
not read tokens beyond this one, this field is set to null. This is true only if
this token is also a regular token. Otherwise, see below for a description of
the contents of this field.
specialToken
public Token specialToken
This field is used to access special tokens that occur prior to this token,
but after the immediately preceding regular (non-special) token. If there
are no such special tokens, this field is set to null. When there are more
than one such special token, this field refers to the last of these special
tokens, which in turn refers to the next previous special token through its
specialToken field, and so on until the first special token (whose
specialToken field is null). The next fields of special tokens refer to other
special tokens that immediately follow it (without an intervening regular
token). If there is no such token, this field is null.
Token ()
public Token()
toString ()
public final String toString()
Returns the image.
Overrides: toString in class Object.
newToken (int)
public static final Token newToken(int ofKind)
Returns a new Token object, by default. However, if you want, you can
create and return subclass objects based on the value of ofKind. Simply
add the cases to the switch for all those special cases. For example, if you
have a subclass of Token called IDToken that you want to create if ofKind is
ID, simlpy add something like : case MyParserConstants.ID : return new
IDToken(); to the following switch statement. Then you can cast
matchedToken variable to the appropriate type and use it in your lexical
actions.
298 IMS Version 7 and Java Application Programming

A.34 Class com.ibm.ims.db.DLIException
Constructors
Method
java.lang.Object
+----java.lang.Throwable
+----java.lang.Exception
+----com.ibm.ims.base.IMSException
+----com.ibm.ims.db.DLIException
public class DLIException extends IMSException
Thrown to indicate an error has occurred. These include all errors that occur
in the Java space, not those that occur while processing an IMS/DLI call and
are propagated back.
DLIException (String)
public DLIException(String message)
Creates an exception with the specified error message. The internal error
code defaults to zero.
Parameters:
message - The error message.
DLIException (String, int)
public DLIException(String message,int code)
Creates an exception with the specified error message and internal error
code.
Parameters:
message - The error message.
code - The internal error code.
getErrorCode ()
public int getErrorCode()
Returns the internal error code. If there is no internal error code, 0 is
returned.
Appendix A. IMS Java package 299

300 IMS Version 7 and Java Application Programming

Appendix B. Debugging and problem determination
B.1 Exceptions
This appendix provides information on debugging and problem determination.
Exceptions are thrown as a result of non-blank status codes and non-zero
return codes (in cases when there were no PCBs to deliver status codes)
from IMS DL/I calls. Exceptions are not all bad; some exceptions are caught
by the following classes of the higher level of IMS Java and responded to in
database and application processing.
B.2 How exceptions map to DL/I status codes
IMSException extends java.lang.Exception. DLIException extends
IMSException by enabling IMS Java to detect errors in IMS DL/I calls from
the database base package and catch them before they are sent to IMS.
The following would be a constructor:
public IMSException(String function,AIB aib,short statcode,String
exceptiontype)
Parameters:
function - the DLI function
aib - AIB
statCode - The status code
exception Type - The exception description message
Useful methods for the IMS Java consumed exceptions are:
getAIB
Returns the IMS AIB from the DL/I call that caused the exception
getStatusCode
Returns the IMS status code from the DL/I call that caused the exception.
Also works with the JavaToDLI set of constants.Status Code will be 0
(zero) for a DLIException.
© Copyright IBM Corp. 2001 301

getFunction
Returns the IMS function from the DL/I call that caused the exception.
These DB classes return false if they receive GE (segment not found) or
GB (endof database) status codes and they are consumed by
DLIConnection (Figure 121).
DLIConnection.getUniqueSegment
DLIConnection.getNextSegment
DLIConnection.getUniqueRecord
DLIConnection.getNextRecord
DLIConnection.getNextSegmentInParent
Figure 121. DLIConnection list
The IMSMessageQueue.getUniqueMessage TM class returns false if it receives a
QC (no more messages) status code. IMSMessageQueue.getNextMessage class
returns false if it receives a QD (no more segments [for multi-segment
messages]) status code. These exceptions are consumed by IMSMessageQueue.
SQLException extends java.lang.Exception by enabling JDBC users to catch
any IMSException, DLIException, or ParseException that are seen by IMS Java
as they are re-thrown as SQL exceptions.
SQLException is thrown to indicate that an error has occurred either in the
Java address space or during database processing.
Each SQLException provides several kinds of information:
1. A string describing the error.
- This string is used as the Java Exception message. It is available
through the use of the getMessage() method.
2. An _SQLstate_ string that follows XOPEN SQLstate conventions.
- The values of the SQLstate string are described in the XOPEN SQL
specification.
3. A chain to a next Exception through the use of the getNextException
method.
- The next exception is used as a source of additional error
information.Status Code Call Methods on Exceptions to Extract
(Figure 122).
302 IMS Version 7 and Java Application Programming

B.3 Sync point failure
final int MAX_IOAREA_SIZE = 054;
AIB aib = new AIB();
byte [] ioArea = new byte [MAX_IOAREA_SIZE];
aib.setResourceName("IOPCB"); // IOPCB is for access the message queue
aib.setOALe gth(80);
try {
JavaToDLI.execute("GN",aib,ioArea);
} catch (IMSException e) {
if (e.getStatusCode() != JavaToDLI.QD)
//process failure
}
Figure 122. Status code call exception example
Related reading
For more information on DL/I Status Codes, see IMS Application
Programming: Transaction Manager, SC26-9425.
If you receive an SY DL/I PCB status code, your IMS Java application SYNC
request call has failed. Table 5 describes the failure.
Table 5. Status code, reason and return code
DL/1 return/
reason
code
PCB
status
code
System
service
call
0108/056C SY IMS Java
sync
Category Description
5 Internal error during
synchpoint porcessing
for an IMS Java
application.AIBERRXT
contains the Sync return code.
A call to the sync point processor (DFSTMS00) returned a non-zero return
code.
Appendix B. Debugging and problem determination 303

B.4 “Try and catch” example
Figure 123 is an example of “try and catch” methods, where the reply is a
method that will place a message on the IMS output queue.
try {
Class.forName("com.ibm.ims.db.DLIDriver");
connection = DriverManager.getConnectio
("jdbc:dli:dealership.applicatio .DealerDatabaseView");
}
catch (Exception e){
reply("Connection not established");
}
Figure 123. Example of “try and catch” methods
304 IMS Version 7 and Java Application Programming

Appendix C. IMS abend codes
This appendix covers abends and pseudoabends.
C.1 Abends and pseudoabends
An abend is the abnormal ending of a program or application. When an abend
error condition occurs, an abend macro is issued either at the point of error
detection or by branching to a routine that issues the abend macro.
There are also pseudoabends wherein the module that detects the error
condition does not issue the abend macro, but instead passes control back to
the IMS call analyzer module, DFSDLA00, which writes the contents of important
control blocks to the system log and indicates a dependent-region abend.
C.2 Abends issued from IMS Java applications
The following are the abends that you might encounter as a result of errors
while running IMS Java applications.
C.2.1 ABENDU0118 - Commit failure
Explanation: This abend is issued if your IMS Java application attempts to
terminate normally without issuing an explicit commit. An explicit commit is
required for each IMS Java application before it can terminate normally.
System action: The application program terminates abnormally.
Programmer response: Increase the size of the I/O area to allow the data to
be returned to the application.
C.2.2 ABENDU0200 - Small I/O area defined
Explanation: A GET type function was issued using the AIB interface that was
expecting data to be returned in the I/O area. However, the length of the IO
area was too small to receive the data
System action: The application program terminates abnormally.
Programmer response: Increase the size of the I/O area to allow the data to
be returned to the application.
© Copyright IBM Corp. 2001 305

C.2.3 ABENDU0462 - Get Unique was not issued
Explanation: An application program was scheduled in a message region
and terminated without successfully issuing a GET UNIQUE for an input
message. The application program did successfully process at least one
other call.
System action: The application program is abnormally terminated, and the
PSB and the SMB are stopped.
Programmer response: Determine the problem in the user message
processing program, correct it, and resubmit the job.
C.2.4 ABENDU0475 - Batch run failure
Explanation: This abend is issued if your IMS Java application attempts to
run as an IMS Batch job. IMS batch does not currently support IMS Java
applications.
System action: The application program terminates abnormally.
Programmer response: Increase the size of the I/O area to allow the data to
be returned to the application.
C.2.5 ABENDU0778 - Rollback failure
Explanation: This abend is issued by the DL/I ROLL call when a program
determines that some of its processing is invalid. ABENDU0778 does not
issue a dump.
System action: The application program is abnormally terminated, and the
PSB and the SMB are stopped.
Programmer response: Determine the problem in the user message
processing program, correct it, and resubmit the job.
306 IMS Version 7 and Java Application Programming

Appendix D. IMS Java tracing facilities
D.1 IMSTrace
This appendix describes IMS Java tracing facilities.
IMSTrace provides you with the ability to debug your Java applications by
tracing, or documenting, the flow of control throughout your application. By
having the ability to set up tracepoints throughout your applications for
output, you can isolate problem areas and, therefore, know where to make
adjustments to produce the results you expect. In addition, because
IMSTrace supports writing input parameters and results, and the
IMS-Java-library-provided routines use this feature, you can verify that
correct results occur across method boundaries.
D.2 Initiating IMSTracing
To debug with IMSTrace, you must first turn on the tracing function by setting
the IMSTrace.traceOn variable to true. Because tracing does not occur until
this variable is set, it is best to do so within a static block of the
IMSApplication subclass. Then, you must decide how closely you want to
trace the IMS Java library’s flow of control, as well as how much tracing you
want to add to your application code.
You determine the amount of tracing in the IMS Java library by setting the
value of IMSTrace.libTraceLevel to one of its predefined values. By default,
this value is set to IMSTrace.TRACE_EXCEPTIONS, which traces the construction
of IMS-Java-library-provided exceptions. IMSTrace also defines constants for
three types of additional tracing. These constants provide successively more
tracing fromIMSTrace.TRACE_CTOR1 (level one tracing of constructions) to
IMSTrace.TRACE_DATA3 (level three tracing of data).
D.3 Setting up tracing for the IMS Java library routines
To turn on the tracing shipped with the IMS Java Library Routines:
1. Turn on the flag enabling tracing. (It is turned off by default.)
IMSTrace.traceO = true;
2. Set the level of tracing for the IMS Java Library Routines.In this example
the construction is traced as is the entry and exit of level one methods:
IMSTrace.libTraceLevel = IMSTrace.TRACE_METHOD;
© Copyright IBM Corp. 2001 307

3. Set an output stream (a print stream or a character output writer) as the
current trace stream. For example:
4. Set the system error stream as the current trace
stream:IMSTrace.setOutputStream(System.err);
5. Set a StringWriter (an in-memory buffer) as the current trace
stream:StringWriter stri gWriter = ew Stri gWriter();
IMSTrace.setOutputWriter(stri gWriter);
These steps are best implemented within a static method of your
IMSApplication subclass main routine:
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();
}
D.4 Adding trace statements to your application
You can add trace statements to your application, similar to those provided by
the IMS Java Library, by defining an integer variable that you test prior to
writing trace statements. Using a variable other than IMSTrace.libTraceLevel
enables you to control the level of tracing in your application independently of
the tracing in the IMS Java library. For example, you can turn off the tracing of
IMS Java Library routines by setting IMSTrace.libTraceLevel to zero while still
tracing your application code.
Follow these steps to add tracing to your application code:
1. Define an integer variable to contain the trace level for
application-provided code:
public class IMSAuto extends IMSApplication{
public int applicationTraceLevel = IMSTrace.TRACE_CTOR3;
308 IMS Version 7 and Java Application Programming

2. Call IMSTrace routines to trace methods, parameters, and return values
as necessary:
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 mai (String args[]){
IMSAuto application = new IMSAuto();
application.begin();
}
public void doBegin() throws IMSException{
if(IMSAuto.applicationTraceLevel >= IMSTrace.TRACE_METHOD1)
IMSTrace.currentTrace().logEntry("IMSAuto.doBegin");
try {
//Add code here ...
String result = method ("Parameter one");
}
finally {
if(IMSAuto.applicationTraceLevel >= IMSTrace.TRACE_METHOD1)
IMSTrace.currentTrace().logExit("IMSAuto.doBegin");
}
}
public String method (String parm ){
if(IMSAuto.applicationTraceLevel >= IMSTrace.TRACE_METHOD2) {
IMSTrace.currentTrace().logE try("IMSAuto.method1");
if(IMSAuto.applicationTraceLevel >= IMSTrace.TRACE_DATA2)
IMSTrace.currentTrace().logParm(“parm1”,parm1);
}
String result = new String();
try {
//Addcodehere...
result = “result”;
}
finally {
if (IMSAuto.applicationTraceLevel >= IMSTrace.TRACE_METHOD2)
IMSTrace.currentTrace().logExit(“IMSAuto.method1”);
}
return result;
}
}
Appendix D. IMS Java tracing facilities 309

310 IMS Version 7 and Java Application Programming

Appendix E. IVP application — Java source (Java to DLI version)
The Installation Verification Program (IVP), mentioned throughout this book,
is outlined in detail in the descriptions of the following classes. The IVP
sample application is a very simple phone book application. Each of the
application programs performs the same add, change, delete, and display
functions. It was created using the lower level database classes:
DLIConnection and the SSA classes (which are built on the JavaToDLI
interface) to the IMS database. More information about the IVP program can
be found in the IMS V7 Installation Volume 1: Installation and Verification,
GC26-9429-00. The IVP Application contains the following methods:
Add Adds an entry into the database.
Delete Deletes an entry from the database.
Display Displays a certain entry in the database.
Reply Sends a response back to the user.
SetOutput Updates the output message.
SetPhonebookSegment Updates the phone book segment.
Update Updates an entry in the database.
UpdateSPA Updates the SPA message.
This application was broken down into the following package:
- samples.ivp
The sample.ivp package contains the following classes:
PhoneBookSegment Maps the A1111111 segment of the DFSIVD2
database.
IVPDatabaseView Contains the segment information for the
database DFSIVD2.
InputMessage This is the default Input Message class. The
IVP program uses it to receive messages from
the message queue.
OutputMessage This is the default Output Message class. The
IVP program uses it to send output to the
message queue.
SPAMessage The IVP program uses this class to save data
between the conversation.
© Copyright IBM Corp. 2001 311

E.1 PhoneBookSegment class
package samples.ivp;
import com.ibm.ims.base.*;
/**
* This is the PhoneBookSegment class which represents the A1111111 segment
* for the DFSIVD2 database which is a root only database having the
* following segment layout:
* BYTES 1-10 LAST NAME (CHARACTER) - KEY
* BYTES 11-20 FIRST NAME (CHARACTER)
* BYTES 21-30 INTERNAL PHONE NUMBER (NUMERIC)
* BYTES 31-37 INTERNAL ZIP (CHARACTER)
* BYTES 38-40 RESERVED
*/
public class PhoneBookSegment extends com.ibm.ims.db.DLISegment
{
staticDLITypeInfo[] typeInfo = {
new DLITypeInfo(“LastName”, DLITypeInfo.CHAR,1,10,”A1111111”),
new DLITypeInfo(“FirstName”, DLITypeInfo.CHAR,11,10),
new DLITypeInfo(“Extension”, DLITypeInfo.CHAR,21,10),
new DLITypeInfo(“ZipCode”, DLITypeInfo.CHAR,31,7)
};
/**
* Constructs an PhoneBookSegment class. Allocates the byte array for the
* segment data. Total segment length is 40 bytes.
*/
protected PhoneBookSegment()
{
super(“A1111111”,typeInfo,40);
}
}
E.2 IVPDatabaseView class
package samples.ivp;
import com.ibm.ims.db.*;
/**
* The TELEPCB class contains the segment info for the database DFSIVD2
*/
public class IVPDatabaseView extends com.ibm.ims.db.DLIDatabaseView
312 IMS Version 7 and Java Application Programming

E.3 InputMessage class
{
static DLISegmentInfo[] segments = {new DLISegmentInfo(new
samples.ivp.PhoneBookSegment(),DLIDatabaseView.ROOT)};
/**
* Constructs a new IVPDatabaseView object.
*/
protected IVPDatabaseView() {
super(“TELEPCB”, segments);
}
}
package samples.ivp;
import com.ibm.ims.base.*;
/** This is the Input Message class for receiving message from the message
* queue
*/
public class InputMessage extends com.ibm.ims.application.IMSFieldMessage
{
static DLITypeInfo[] fieldInfo = {
new DLITypeInfo(“Reserved”,DLITypeInfo.CHAR,1,4),
new DLITypeInfo(“ProcessCode”,DLITypeInfo.CHAR,5,8),
new DLITypeInfo(“LastName”,DLITypeInfo.CHAR,13,10),
new DLITypeInfo(“FirstName”,DLITypeInfo.CHAR,23,10),
new DLITypeInfo(“Extension”,DLITypeInfo.CHAR,33,10),
new DLITypeInfo(“ZipCode”,DLITypeInfo.CHAR,43,7)
};
/**
* Constructs an InputMessage. It allocates the byte array
* for the input message. Total data length is 49 bytes.
* The input message data has the following layout format
* as defined in the MID:
* Reserved ( 4 bytes)
* Process Code ( 8 bytes)
* Input Data : (37 bytes total)
* - Last Name (10 bytes)
* - First Name (10 bytes)
* - Extension Number (10 bytes)
* - Internal Zip Code ( 7 bytes)
*/
public InputMessage()
Appendix E. IVP application — Java source (Java to DLI version) 313

{
}
}
E.4 OutputMessage class
super(fieldInfo,49, false);
package samples.ivp;
import com.ibm.ims.base.*;
/**
* This is the OuputMessage class which the IVP program uses to send output
* to the message queue.
*/
public class OutputMessage extends com.ibm.ims.application.IMSFieldMessage
{
static DLITypeInfo[] fieldInfo = {
new DLITypeInfo(“Message”,DLITypeInfo.CHAR,1,40),
new DLITypeInfo(“ProcessCode”,DLITypeInfo.CHAR,41,8),
new DLITypeInfo(“LastName”,DLITypeInfo.CHAR,49,10),
new DLITypeInfo(“FirstName”,DLITypeInfo.CHAR,59,10),
new DLITypeInfo(“Extension”,DLITypeInfo.CHAR,69,10),
new DLITypeInfo(“ZipCode”,DLITypeInfo.CHAR,79,7),
new DLITypeInfo(“SegmentNumber”,DLITypeInfo.CHAR,86,4)
};
/**
* Constructs an OutputMessage. It allocates the byte array
* for the output message. Total data length is 89 bytes.
* The output message data has the following layout format:
* Output Message (40 bytes)
* Process Code ( 8 bytes)
* Output Data (37 bytes)
* - Last Name (10 bytes)
* - First Name (10 bytes)
* - Extension Number (10 bytes)
* - Internal Zip Code ( 7 bytes)
* Segment Number ( 4 bytes)
*/
public OutputMessage()
{
super(fieldInfo,89, false);
}
}
314 IMS Version 7 and Java Application Programming

E.5 SPAMessage class
package samples.ivp;
import com.ibm.ims.base.*;
/**
* This is the SPAMessage class which the IVP program uses to save data
* between the conversation.
*/
public class SPAMessage extends com.ibm.ims.application.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)
};
/**
* Constructs a SPAMessage. It allocates the byte array
* for the spa message. Total data length is 66 bytes.
* The output message data has the following layout format:
* Session Number (2 bytes)
* Process Code (8 bytes)
* SPA Data (37 bytes total)
* - Last Name (10 bytes)
* - First Name (10 bytes)
* - Extension Number (10 bytes)
* - Internal Zip Code ( 7 bytes)
* Reserved (19 bytes)
*/
public SPAMessage()
{
super(fieldInfo, 66, true);
}
/**
* Increment the session number for the conversation.
*/
public void incrementSessionNumber() throws IMSException
{
setShort(“SessionNumber”,(short)(getShort(“SessionNumber”)+1));
}
}
Appendix E. IVP application — Java source (Java to DLI version) 315

E.6 Installation Verification Program (IVP) application
package samples.ivp;
//
// CONV TITLE ‘INSTALLATION VERIFICATION PROCEDURE - CONVERSATIONAL’
//-------------------------------------------------------------------
//
// APPLICATION : IMS INSTALLATION VERIFICATION PROCEDURE
// CONVERSATIONAL MPP PROGRAM HDAM/VSAM
// TRANSACTION : IVTCC
// PSB : DFSIVP32
// DATABASE : DFSIVD2
//
//-------------------------------------------------------------------
//
// Licensed Materials - Property of IBM
// “Restricted Materials of IBM”
// 5655-158 (C) Copyright IBM Corp. 1999
//
//-------------------------------------------------------------------
//
// INPUT:
// TELEPHONE DIRECTORY SYSTEM
// PROCESS CODE : CCCCCCCC
// LAST NAME : XXXXXXXXXX
// FIRST NAME : XXXXXXXXXX
// EXTENTION# : N-NNN-NNNN
// INTERNAL ZIP : XXX/XXX
//
// CCCCCCCC = COMMAND
// ADD = INSERT ENTRY IN DB
// TADD = NOT SUPPORTED. DEFAULT TO ADD
// DELETE = DELETE ENTRY FROM DB
// UPDATE = UPDATE ENTRY FROM DB
// DISPLAY = DISPLAY ENTRY
// END = TERMINATE CONVERSATION
//
//-------------------------------------------------------------------
import com.ibm.ims.base.*;
import com.ibm.ims.application.*;
import com.ibm.ims.db.*;
/**
* The IVP class is the Installation Verification Program which is
316 IMS Version 7 and Java Application Programming

* a conversational program that runs in the IMS MPP region.
* This program works with the DFSIVD2 database, which defines
* the phone book directory.
**/
public class IVP extends com.ibm.ims.application.IMSApplication
{
private IMSMessageQueue msgQ = null;
private IVPDatabaseView dbView = null;
private DLIConnection connection = null;
private int segNum = 0;
/** Constructs a new IVP object. */
public IVP() {}
/**
* Add an entry into the database.
* All fields for the segment (Last Name, First Name, Extension Number,
* and Internal Zip Code) should be entered for insert.
* @param inputMessage - the input message from the user
* @param outputMessage - the output message for this transaction
*/
public void add(InputMessage inputMessage, OutputMessage outputMessage)
throws IMSException
{
PhoneBookSegment phonebookSegment = new PhoneBookSegment();
SSA ssa = SSA.createInstance(“PhoneBookSegment”);
SSAList ssaList = SSAList.createInstance();
ssaList.addSSA(ssa);
// Check for input fields
if (inputMessage.getString(“FirstName”).trim().equals(““)
|| inputMessage.getString(“LastName”).trim().equals(““)
|| inputMessage.getString(“Extension”).trim().equals(““)
|| inputMessage.getString(“ZipCode”).trim().equals(““))
{ // Not enough input data
outputMessage.setString(“Message”,
”DATA IS NOT ENOUGH. PLEASE KEY IN MORE”);
}
else
{
try
{
setPhonebookSegment(inputMessage,phonebookSegment);
// Insert the new segment into the database
connection.insertSegment(phonebookSegment,ssaList);
outputMessage.setString(“Message”,”ENTRY WAS ADDED”);
}
Appendix E. IVP application — Java source (Java to DLI version) 317

}
catch (Exception e)
{ // Error in inserting
outputMessage.setString(“Message”,”ADDITION OF ENTRY HAS FAILED”);
}
}
setOutput(inputMessage, outputMessage);
/**
* Delete an entry from the database.
* @param inputMessage - the input message from the user
* @param outputMessage - the output message for this transaction
*/
public void delete(InputMessage inputMessage, OutputMessage outputMessage)
throws IMSException
{
PhoneBookSegment phonebookSegment = new PhoneBookSegment();
SSA ssa = SSA.createInstance(“PhoneBookSegment”);
SSAList ssaList = SSAList.createInstance();
// Set the SSA List for retrieving the segment from the database
ssa.addQualificationStatement(“LastName”,
SSA.EQUALS,inputMessage.getString(“LastName”));
ssaList.addSSA(ssa);
// Check if the requested segment is found in the database
if (!connection.getUniqueSegment(phonebookSegment,ssaList))
{ // Requested data not found in database
outputMessage.setString(“Message”,”SPECIFIED PERSON WAS NOT FOUND”);
}
else
{
try
{ // Delete the segment
connection.deleteSegments();
outputMessage.setString(“Message”,”ENTRY WAS DELETED”);
}
catch (IMSException e)
{ // Error in deleting the data
outputMessage.setString(“Message”,”DELETION OF ENTRY HAS FAILED”);
}
}
setOutput(inputMessage, outputMessage);
}
/**
* Display a certain entry from the database.
* @param inputMessage - the input message from the user
* @param outputMessage - the output message for this transaction
318 IMS Version 7 and Java Application Programming

*/
public void display(InputMessage inputMessage, OutputMessage outputMessage)
throws IMSException
{
PhoneBookSegment phonebookSegment = new PhoneBookSegment();
SSA ssa = SSA.createInstance(“PhoneBookSegment”);
SSAList ssaList = SSAList.createInstance();
// Set the SSA List for retrieving the segment from the database
ssa.addQualificationStatement(“LastName”,
SSA.EQUALS,inputMessage.getString(“LastName”));
ssaList.addSSA(ssa);
// Retrieve the segment from the database
if (!connection.getUniqueSegment(phonebookSegment,ssaList))
{ // Data not found in database
setOutput(inputMessage, outputMessage);
outputMessage.setString(“Message”,”SPECIFIED PERSON IS NOT FOUND”);
}
else
{ // Set output data fields
setOutput(phonebookSegment, outputMessage);
outputMessage.setString(“Message”,”ENTRY WAS DISPLAYED”);
}
}
/**
* This is the IVP application program.
* It first reads the SPA message and determines the state of the
* conversation program. It then reads the user input request and
* process the database command and send a response back to the
* user according to the status of the processing.
*/
public void doBegin() throws IMSException
{
msgQ = new IMSMessageQueue();
dbView = new IVPDatabaseView();
connection = DLIConnection.createInstance(dbView);
InputMessage inputMessage = new InputMessage();
OutputMessage outputMessage = new OutputMessage();
SPAMessage spaMessage = new SPAMessage();
String procCode = null;
boolean msgReceived = false;
try
{ // Get the SPA data
msgReceived = msgQ.getUniqueMessage(spaMessage);
}
catch (IMSException e)
Appendix E. IVP application — Java source (Java to DLI version) 319

{
if (e.getStatusCode() !=
JavaToDLI.MESSAGE_QUEUED_PRIOR_TO_LAST_START)
throw e;
}
if (!msgReceived)
outputMessage.setString(“Message”,”UNABLE TO READ SPA”);
else if (!msgQ.getNextMessage(inputMessage))
// No input message received
outputMessage.setString(“Message”,”NO INPUT MESSAGE”);
else if ((spaMessage.getShort(“SessionNumber”)==0)
&&
(!inputMessage.getString(“ProcessCode”).trim().equals(“END”))
&& (inputMessage.getString(“LastName”).trim().equals(““)))
// New Conversation. User has to specify last name.
outputMessage.setString(“Message”,”LAST NAME WAS NOT SPECIFIED”);
else
{
try
{
procCode = inputMessage.getString(“ProcessCode”).trim();
if (spaMessage.getShort(“SessionNumber”) !=0)
{ // Check if process code is specified. If not, use SPA data as
// default
if (procCode.equals(““))
inputMessage.setString(“ProcessCode”,
spaMessage.getString(“ProcessCode”));
// Check if last name is specified. If not, use SPA data as
// default
if (inputMessage.getString(“LastName”).equals(““))
inputMessage.setString(“LastName”,
spaMessage.getString(“LastName”));
}
// Determine which command was requested
if (procCode.equals(“ADD”) || procCode.equals(“TADD”))
add(inputMessage, outputMessage); // Add the entry to the
// database
else if (procCode.equals(“DELETE”))
delete(inputMessage, outputMessage);// Delete the entry from
// the database
else if (procCode.equals(“UPDATE”))
update(inputMessage, outputMessage);// Update the entry in the
// database
else if (procCode.equals(“DISPLAY”))
display(inputMessage, outputMessage);// Display the data from
// the database
else
320 IMS Version 7 and Java Application Programming

}
outputMessage.setString(“Message”,
“PROCESS CODE WAS INVALID”);
}
catch (Exception e)
{
outputMessage.setString(“Message”,
“Request failed. “ + e.toString());
}
}
// Update the spa and send a response back to the user.
updateSPA(inputMessage, spaMessage, procCode);
reply(outputMessage, procCode);
// Commit this transaction.
IMSTransaction.getTransaction().commit();
/** main entry point of the IVP program **/
public static void main(String args[])
{
IVP ivp = new IVP();
ivp.begin();
}
/**
* Send a response back to the user.
* @param outputMessage - the output message to be sent to user
* @param procCode - the process code for this transaction
*/
public void reply(OutputMessage outputMessage, String procCode) throws
IMSException
{
if (procCode.equals(“END”))
outputMessage.setString(“Message”,”CONVERSATION HAS ENDED”);
msgQ.insertMessage(outputMessage);
}
/**
* Update the output message.
* @param inputMessage - the input message from the user
* @param outputMessage - the output message to be updated
*/
public void setOutput(InputMessage inputMessage, OutputMessage
outputMessage) throws IMSException
{
// Set output data fields
outputMessage.setString(“ProcessCode”,
inputMessage.getString(“ProcessCode”));
Appendix E. IVP application — Java source (Java to DLI version) 321

}
outputMessage.setString(“LastName”,
inputMessage.getString(“LastName”));
outputMessage.setString(“FirstName”,
inputMessage.getString(“FirstName”));
outputMessage.setString(“Extension”,
inputMessage.getString(“Extension”));
outputMessage.setString(“ZipCode”,
inputMessage.getString(“ZipCode”));
/**
* Update the output message.
* @param phonebookSegment - the segment info from the database
* @param outputMessage - the output message to be updated
*/
public void setOutput(PhoneBookSegment phonebookSegment, OutputMessage
outputMessage) throws IMSException
{
// Set output data fields
outputMessage.setString(“LastName”,
phonebookSegment.getString(“LastName”));
outputMessage.setString(“FirstName”,
phonebookSegment.getString(“FirstName”));
outputMessage.setString(“Extension”,
phonebookSegment.getString(“Extension”));
outputMessage.setString(“ZipCode”,
phonebookSegment.getString(“ZipCode”));
}
/**
* Update the phone book segment
* @param inputMessage - the input message from the user
* @param phonebookSegment - the phone book segment to be updated
*/
public void setPhonebookSegment(InputMessage inputMessage, PhoneBookSegment
phonebookSegment) throws IMSException
{
// Set phone book segment data fields
phonebookSegment.setString(“LastName”,
inputMessage.getString(“LastName”));
phonebookSegment.setString(“FirstName”,
inputMessage.getString(“FirstName”));
phonebookSegment.setString(“Extension”,
inputMessage.getString(“Extension”));
phonebookSegment.setString(“ZipCode”,
inputMessage.getString(“ZipCode”));
}
322 IMS Version 7 and Java Application Programming

**
* Update an entry in the database.
* @param inputMessage - the input message from the user
* @param outputMessage - the output message for this transaction
*/
public void update(InputMessage inputMessage, OutputMessage outputMessage)
throws IMSException
{
PhoneBookSegment phonebookSegment = new PhoneBookSegment();
SSA ssa = SSA.createInstance(“PhoneBookSegment”);
SSAList ssaList = SSAList.createInstance();
// Set the SSA List for retrieving the segment from the database
ssa.addQualificationStatement(“LastName”,
SSA.EQUALS,inputMessage.getString(“LastName”));
ssaList.addSSA(ssa);
// Retrieve the segment from the database
if (!connection.getUniqueSegment(phonebookSegment,ssaList))
{ // Requested data not found in database
outputMessage.setString(“Message”,”SPECIFIED PERSON WAS NOT FOUND”);
}
else if (inputMessage.getString(“FirstName”).equals(““)
|| inputMessage.getString(“LastName”).equals(““)
|| inputMessage.getString(“Extension”).equals(““)
|| inputMessage.getString(“ZipCode”).equals(““))
{ // Requested input data not enough
outputMessage.setString(“Message”,
”DATA IS NOT ENOUGH. PLEASE KEY IN MORE”);
}
else
{
try
{ // Update the new entry
setPhonebookSegment(inputMessage,phonebookSegment);
connection.replaceSegment(phonebookSegment);
outputMessage.setString(“Message”,”ENTRY WAS UPDATED”);
}
catch (IMSException e)
{ // Error with the update
outputMessage.setString(“Message”,”UPDATE OF ENTRY HAS FAILED”);
}
}
// Update the output data
setOutput(inputMessage, outputMessage);
}
/**
Appendix E. IVP application — Java source (Java to DLI version) 323

* Update the SPA message.
* @param inputMessage - the input message from the user
* @param spaMessage - the spa message to be updated
*/
public void updateSPA(InputMessage inputMessage, SPAMessage spaMessage,
String procCode) throws IMSException
{
if (!procCode.equals(“END”))
{
// Set spa data fields
spaMessage.setString(“ProcessCode”,
inputMessage.getString(“ProcessCode”));
spaMessage.setString(“LastName”,inputMessage.getString(“LastName”));
spaMessage.setString(“FirstName”,
inputMessage.getString(“FirstName”));
spaMessage.setString(“Extension”,
inputMessage.getString(“Extension”));
spaMessage.setString(“ZipCode”,
inputMessage.getString(“ZipCode”));
spaMessage.incrementSessionNumber();
msgQ.insertMessage(spaMessage);
}
else
msgQ.insertMessage(spaMessage, true);
}
}
324 IMS Version 7 and Java Application Programming

Appendix F. IVP application — Java source (JDBC version)
The Installation Verification Program (IVP), mentioned throughout this book is
outlined in detail in the following classes. The IVP sample application is a
very simple phone book application. Each of the application programs
performs the same add, change, delete, and display functions. It was created
using the JDBC IMS interface. More information about the IVP program can
be found in the IMS V7 Installation Volume 1: Installation and Verification,
GC26-9429-00. The IVP Application contains the following methods:
Add Adds an entry into the database.
Delete Deletes an entry from the database.
Display Displays a certain entry in the database.
Reply Sends a response back to the user.
SetOutput Updates the output message.
SetPhonebookSegment Updates the phone book segment.
Update Updates an entry in the database.
UpdateSPA Updates the SPA message.
This application was broken down into the following package:
- samples.jdbc
The sample.ivp package contains the following classes:
PhoneBookSegment Maps the A1111111 segment of the DFSIVD2
database.
IVPDatabaseView Contains the segment information for the
database DFSIVD2.
InputMessage This is the default Input Message class. The
IVP program uses it to receive messages from
the message queue.
OutputMessage This is the default Output Message class. The
IVP program uses it to send output to the
message queue.
SPAMessage The IVP program uses this class to save data
between the conversation.
© Copyright IBM Corp. 2001 325

F.1 PhoneBookSegment class
package samples.jdbc;
import com.ibm.ims.base.*;
/**
* This is the PhoneBookSegment class which represents the A1111111 segment
* for the DFSIVD2 database which is a root only database having the
* following segment layout:
* BYTES 1-10 LAST NAME (CHARACTER) - KEY
* BYTES 11-20 FIRST NAME (CHARACTER)
* BYTES 21-30 INTERNAL PHONE NUMBER (NUMERIC)
* BYTES 31-37 INTERNAL ZIP (CHARACTER)
* BYTES 38-40 RESERVED
*/
public class PhoneBookSegment extends com.ibm.ims.db.DLISegment
{
staticDLITypeInfo[] typeInfo = {
new DLITypeInfo(“LastName”, DLITypeInfo.CHAR,1,10,”A1111111”),
new DLITypeInfo(“FirstName”, DLITypeInfo.CHAR,11,10),
new DLITypeInfo(“Extension”, DLITypeInfo.CHAR,21,10),
new DLITypeInfo(“ZipCode”, DLITypeInfo.CHAR,31,7)
};
/**
* Constructs an PhoneBookSegment class. Allocates the byte array for the
* segment data. Total segment length is 40 bytes.
*/
protected PhoneBookSegment()
{
super(“A1111111”,typeInfo,40);
}
}
F.2 IVPDatabaseView class
package samples.jdbc;
import com.ibm.ims.db.*;
/**
* The TELEPCB class contains the segment info for the database DFSIVD2
*/
public class IVPDatabaseView extends com.ibm.ims.db.DLIDatabaseView
{
326 IMS Version 7 and Java Application Programming

F.3 InputMessage class
static DLISegmentInfo[] segments = {new DLISegmentInfo(new
samples.jdbc.PhoneBookSegment(),DLIDatabaseView.ROOT)};
/**
* Constructs a new IVPDatabaseView object.
*/
protected IVPDatabaseView() {
super(“TELEPCB”, segments);
}
}
package samples.jdbc;
import com.ibm.ims.base.*;
/** This is the Input Message class for receiving message from the message
queue */
public class InputMessage extends com.ibm.ims.application.IMSFieldMessage
{
static DLITypeInfo[] fieldInfo = {
new DLITypeInfo(“Reserved”,DLITypeInfo.CHAR,1,4),
new DLITypeInfo(“ProcessCode”,DLITypeInfo.CHAR,5,8),
new DLITypeInfo(“LastName”,DLITypeInfo.CHAR,13,10),
new DLITypeInfo(“FirstName”,DLITypeInfo.CHAR,23,10),
new DLITypeInfo(“Extension”,DLITypeInfo.CHAR,33,10),
new DLITypeInfo(“ZipCode”,DLITypeInfo.CHAR,43,7)
};
/**
* Constructs an InputMessage. It allocates the byte array
* for the input message. Total data length is 49 bytes.
* The input message data has the following layout format
* as defined in the MID:
* Reserved ( 4 bytes)
* Process Code ( 8 bytes)
* Input Data : (37 bytes total)
* - Last Name (10 bytes)
* - First Name (10 bytes)
* - Extension Number (10 bytes)
* - Internal Zip Code ( 7 bytes)
*/
public InputMessage()
{
Appendix F. IVP application — Java source (JDBC version) 327

}
}
F.4 OutputMessage class
super(fieldInfo,49, false);
package samples.jdbc;
import com.ibm.ims.base.*;
/**
* This is the OuputMessage class which the IVP program uses to send output
* to the message queue.
*/
public class OutputMessage extends com.ibm.ims.application.IMSFieldMessage
{
static DLITypeInfo[] fieldInfo = {
new DLITypeInfo(“Message”,DLITypeInfo.CHAR,1,40),
new DLITypeInfo(“ProcessCode”,DLITypeInfo.CHAR,41,8),
new DLITypeInfo(“LastName”,DLITypeInfo.CHAR,49,10),
new DLITypeInfo(“FirstName”,DLITypeInfo.CHAR,59,10),
new DLITypeInfo(“Extension”,DLITypeInfo.CHAR,69,10),
new DLITypeInfo(“ZipCode”,DLITypeInfo.CHAR,79,7),
new DLITypeInfo(“SegmentNumber”,DLITypeInfo.CHAR,86,4)
};
/**
* Constructs an OutputMessage. It allocates the byte array
* for the output message. Total data length is 89 bytes.
* The output message data has the following layout format:
* Output Message (40 bytes)
* Process Code ( 8 bytes)
* Output Data (37 bytes)
* - Last Name (10 bytes)
* - First Name (10 bytes)
* - Extension Number (10 bytes)
* - Internal Zip Code ( 7 bytes)
* Segment Number ( 4 bytes)
*/
public OutputMessage()
{
super(fieldInfo,89, false);
}
}
328 IMS Version 7 and Java Application Programming

F.5 SPAMessage class
package samples.jdbc;
import com.ibm.ims.base.*;
/**
* This is the SPAMessage class which the IVP program uses to save data
* between the conversation.
*/
public class SPAMessage extends com.ibm.ims.application.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)
};
/**
* Constructs a SPAMessage. It allocates the byte array
* for the spa message. Total data length is 66 bytes.
* The output message data has the following layout format:
* Session Number (2 bytes)
* Process Code (8 bytes)
* SPA Data (37 bytes total)
* - Last Name (10 bytes)
* - First Name (10 bytes)
* - Extension Number (10 bytes)
* - Internal Zip Code ( 7 bytes)
* Reserved (19 bytes)
*/
public SPAMessage()
{
super(fieldInfo, 66, true);
}
/**
* Increment the session number for the conversation.
*/
public void incrementSessionNumber() throws IMSException
{
setShort(“SessionNumber”,(short)(getShort(“SessionNumber”)+1));
Appendix F. IVP application — Java source (JDBC version) 329

}
}
F.6 Installation Verification Program (IVP) application
package samples.jdbc;
//
// CONV TITLE ‘INSTALLATION VERIFICATION PROCEDURE - CONVERSATIONAL’
//-------------------------------------------------------------------
//
// APPLICATION : IMS INSTALLATION VERIFICATION PROCEDURE
// CONVERSATIONAL MPP PROGRAM HDAM/VSAM
// TRANSACTION : IVTCC
// PSB : DFSIVP32
// DATABASE : DFSIVD2
//
//-------------------------------------------------------------------
//
// Licensed Materials - Property of IBM
// “Restricted Materials of IBM”
// 5655-158 (C) Copyright IBM Corp. 1999
//
//-------------------------------------------------------------------
//
// INPUT:
// TELEPHONE DIRECTORY SYSTEM
// PROCESS CODE : CCCCCCCC
// LAST NAME : XXXXXXXXXX
// FIRST NAME : XXXXXXXXXX
// EXTENTION# : N-NNN-NNNN
// INTERNAL ZIP : XXX/XXX
//
// CCCCCCCC = COMMAND
// ADD = INSERT ENTRY IN DB
// TADD = NOT SUPPORTED. DEFAULT TO ADD
// DELETE = DELETE ENTRY FROM DB
// UPDATE = UPDATE ENTRY FROM DB
// DISPLAY = DISPLAY ENTRY
// END = TERMINATE CONVERSATION
//
//-------------------------------------------------------------------
import com.ibm.ims.base.*;
import com.ibm.ims.application.*;
330 IMS Version 7 and Java Application Programming

import com.ibm.ims.db.*;
import java.sql.*;
/**
* The IVP class is the Installation Verification Program which is
* a conversational program that runs in the IMS MPP region.
* This program works with the DFSIVD2 database, which defines
* the phone book directory.
**/
public class IVP extends IMSApplication
{
private IMSMessageQueue msgQ = null;
private Connection connection = null;
/** Constructs a new IVP object. */
public IVP()
{
}
/**
* Add an entry into the database.
* All fields for the segment (Last Name, First Name, Extension Number,
* and Internal Zip Code) should be entered for insert.
* @param inputMessage - the input message from the user
* @param outputMessage - the output message for this transaction
*/
public void add(InputMessage inputMessage, OutputMessage outputMessage)
throws IMSException
{
String firstName = inputMessage.getString(“FirstName”).trim();
String lastName = inputMessage.getString(“LastName”).trim();
String extension = inputMessage.getString(“Extension”).trim();
String zip = inputMessage.getString(“ZipCode”).trim();
// Check for input fields
if (firstName.equals(““)
|| lastName.equals(““)
|| extension.equals(““)
|| zip.equals(““))
{ // Not enough input data
outputMessage.setString(“Message”,”DATA IS NOT ENOUGH. PLEASE KEY IN
MORE”);
}
else
{
try
Appendix F. IVP application — Java source (JDBC version) 331

{ // Insert the new segment into the database
Statement statement = connection.createStatement();
statement.executeUpdate(“INSERT INTO PhoneBookSegment (FirstName,
LastName, Extension, ZipCode) “
+ “VALUES (‘” + firstName + “‘, ‘” + lastName + “‘, ‘”
+ extension + “‘, ‘” + zip + “‘)”);
outputMessage.setString(“Message”,”ENTRY WAS ADDED”);
}
catch (Exception e)
{ // Error in inserting
outputMessage.setString(“Message”,”ADDITION OF ENTRY HAS FAILED”);
}
}
setOutput(inputMessage, outputMessage);
}
/**
* Delete an entry from the database.
* @param inputMessage - the input message from the user
* @param outputMessage - the output message for this transaction
*/
public void delete(InputMessage inputMessage, OutputMessage outputMessage)
throws IMSException
{
try
{ // Delete the segment
Statement statement = connection.createStatement();
statement.executeUpdate(“DELETE FROM PhoneBookSegment “
+ “WHERE LastName = ‘” + inputMessage.getString(“LastName”)
+ “‘”);
outputMessage.setString(“Message”,”ENTRY WAS DELETED”);
}
catch (Exception e)
{ // Error in deleting the data
outputMessage.setString(“Message”,”DELETION OF ENTRY HAS FAILED”);
}
setOutput(inputMessage, outputMessage);
}
/**
* Display a certain entry from the database.
* @param inputMessage - the input message from the user
* @param outputMessage - the output message for this transaction
*/
public void display(InputMessage inputMessage, OutputMessage outputMessage)
throws IMSException
{
332 IMS Version 7 and Java Application Programming

try
{
Statement statement = connection.createStatement();
ResultSet result = statement.executeQuery(“SELECT * FROM
PhoneBookSegment “
+ “WHERE LastName = ‘” + inputMessage.getString(“LastName”)
+ “‘”);
setOutput(result, outputMessage);
outputMessage.setString(“Message”,”ENTRY WAS DISPLAYED”);
}
catch (Exception e)
{ // Set output data fields
setOutput(inputMessage, outputMessage);
outputMessage.setString(“Message”,”SPECIFIED PERSON IS NOT FOUND”);
}
}
/**
* This is the IVP application program.
* It first reads the SPA message and determines the state of the
* conversation program. It then reads the user input request and
* process the database command and send a response back to the
* user according to the status of the processing.
*/
public void doBegin() throws IMSException
{
msgQ = new IMSMessageQueue();
InputMessage inputMessage = new InputMessage();
OutputMessage outputMessage = new OutputMessage();
SPAMessage spaMessage = new SPAMessage();
boolean msgReceived = false;
String procCode = null;
String errorMessage = null;
try
{
Class.forName(“com.ibm.ims.db.DLIDriver”);
connection = DriverManager.getConnection(
“jdbc:dli:samples.jdbc.IVPDatabaseView”);
// Get the SPA data
msgReceived = msgQ.getUniqueMessage(spaMessage);
if (!msgReceived)
errorMessage = “UNABLE TO READ SPA”;
}
catch (IMSException e)
{
if (e.getStatusCode() !=
Appendix F. IVP application — Java source (JDBC version) 333

JavaToDLI.MESSAGE_QUEUED_PRIOR_TO_LAST_START)
throw e;
}
catch (Exception e)
{
errorMessage = “Could not load DLIDriver”;
}
if (errorMessage != null)
{
if (!msgQ.getNextMessage(inputMessage))
// No input message received
errorMessage = “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.
errorMessage = “LAST NAME WAS NOT SPECIFIED”;
else
{
try
{
procCode = inputMessage.getString(“ProcessCode”).trim();
if (spaMessage.getShort(“SessionNumber”) !=0)
{ // Check if process code is specified. If not, use SPA data
// as default
if (procCode.equals(““))
inputMessage.setString(“ProcessCode”,
spaMessage.getString(“ProcessCode”));
// Check if last name is specified. If not, use SPA data as
// default
if (inputMessage.getString(“LastName”).equals(““))
inputMessage.setString(“LastName”,
spaMessage.getString(“LastName”));
}
// Determine which command was requested
if (procCode.equals(“ADD”) || procCode.equals(“TADD”))
add(inputMessage, outputMessage); // Add the entry to the
// database
else if (procCode.equals(“DELETE”))
delete(inputMessage, outputMessage);// Delete the entry
// from the database
else if (procCode.equals(“UPDATE”))
update(inputMessage, outputMessage);// Update the entry in
// the database
else if (procCode.equals(“DISPLAY”))
display(inputMessage, outputMessage);// Display the data
334 IMS Version 7 and Java Application Programming

}
// from the database
else
errorMessage = “PROCESS CODE WAS INVALID”;
}
catch (Exception e)
{
outputMessage.setString(“Message”,
“Request failed. “ + e.toString());
}
}
}
// Update the spa and send a response back to the user.
updateSPA(inputMessage, spaMessage, procCode);
if (errorMessage != null)
outputMessage.setString(“Message”, errorMessage);
reply(outputMessage, procCode);
// Commit this transaction.
IMSTransaction.getTransaction().commit();
/** main entry point of the IVP program **/
public static void main(String args[])
{
IVP ivp = new IVP();
ivp.begin();
}
/**
* Send a response back to the user.
* @param outputMessage - the output message to be sent to user
* @param procCode - the process code for this transaction
*/
public void reply(OutputMessage outputMessage, String procCode) throws
IMSException
{
if (procCode.equals(“END”))
outputMessage.setString(“Message”,”CONVERSATION HAS ENDED”);
msgQ.insertMessage(outputMessage);
}
/**
* Update the output message.
* @param result - the segment info from the database
* @param outputMessage - the output message to be updated
*/
public void setOutput(ResultSet result, OutputMessage outputMessage) throws
SQLException, IMSException
Appendix F. IVP application — Java source (JDBC version) 335

{
}
// Set output data fields
outputMessage.setString(“LastName”,result.getString(“LastName”));
outputMessage.setString(“FirstName”,result.getString(“FirstName”));
outputMessage.setString(“Extension”,result.getString(“Extension”));
outputMessage.setString(“ZipCode”,result.getString(“ZipCode”));
/**
* Update the output message.
* @param inputMessage - the input message from the user
* @param outputMessage - the output message to be updated
*/
public void setOutput(InputMessage inputMessage, OutputMessage
outputMessage) throws IMSException
{
// Set output data fields
outputMessage.setString(“ProcessCode”,
inputMessage.getString(“ProcessCode”));
outputMessage.setString(“LastName”,
inputMessage.getString(“LastName”));
outputMessage.setString(“FirstName”,
inputMessage.getString(“FirstName”));
outputMessage.setString(“Extension”,
inputMessage.getString(“Extension”));
outputMessage.setString(“ZipCode”,
inputMessage.getString(“ZipCode”));
}
/**
* Update an entry in the database.
* @param inputMessage - the input message from the user
* @param outputMessage - the output message for this transaction
*/
public void update(InputMessage inputMessage, OutputMessage outputMessage)
throws IMSException
{
String firstName = inputMessage.getString(“FirstName”).trim();
String lastName = inputMessage.getString(“LastName”).trim();
String extension = inputMessage.getString(“Extension”).trim();
String zip = inputMessage.getString(“ZipCode”).trim();
// Check for input fields
if (firstName.equals(““)
|| lastName.equals(““)
|| extension.equals(““)
|| zip.equals(““))
{ // Requested input data not enough
336 IMS Version 7 and Java Application Programming

}
outputMessage.setString(“Message”,
”DATA IS NOT ENOUGH. PLEASE KEY IN MORE”);
}
else
{
try
{ // Update the new entry
Statement statement = connection.createStatement();
statement.executeQuery(“UPDATE PhoneBookSegment
SET FirstName = ‘” + firstName
+ “‘, Extension = ‘” + extension
+ “‘, ZipCode = ‘” +zip+“‘ “
+ “WHERE LastName = ‘” + inputMessage.getString(“LastName”)
+ “‘”);
outputMessage.setString(“Message”,”ENTRY WAS UPDATED”);
}
catch (Exception e)
{ // Error with the update
outputMessage.setString(“Message”,”UPDATE OF ENTRY HAS FAILED”);
}
}
// Update the output data
setOutput(inputMessage, outputMessage);
/**
* Update the SPA message.
* @param inputMessage - the input message from the user
* @param spaMessage - the spa message to be updated
*/
public void updateSPA(InputMessage inputMessage, SPAMessage spaMessage,
String procCode) throws IMSException
{
if (!procCode.equals(“END”))
{
// Set spa data fields
spaMessage.setString(“ProcessCode”,inputMessage.getString(“ProcessCode”));
spaMessage.setString(“LastName”,inputMessage.getString(“LastName”));
spaMessage.setString(“FirstName”,inputMessage.getString(“FirstName”));
spaMessage.setString(“Extension”,inputMessage.getString(“Extension”));
spaMessage.setString(“ZipCode”,inputMessage.getString(“ZipCode”));
spaMessage.incrementSessionNumber();
msgQ.insertMessage(spaMessage);
}
Appendix F. IVP application — Java source (JDBC version) 337

}
}
else
msgQ.insertMessage(spaMessage, true);
338 IMS Version 7 and Java Application Programming

Appendix G. IVP application — COBOL source
G.1 IVP application
The application code for the Installation Verification Program (IVP), which is
mentioned throughout this book, is listed here.
More information about the IVP program can be found in the IMS V7
Installation Volume 1: Installation and Verification, GC26-9429-00.
IDENTIFICATION DIVISION.
PROGRAM-ID. DFSIVA34.
*
********************************************************@SCPYRT**
* *
* Licensed Materials - Property of IBM *
* *
* “Restricted Materials of IBM” *
* *
* 5655-B01 (C) Copyright IBM Corp. 1991,1998 *
* *
********************************************************@ECPYRT**
*
* APPLICATION : CONVERSATIONAL PROGRAM
* TRANSACTION : IVTCB
* PSB : DFSIVP34
* DATABASE : DFSIVD2
* INPUT:
* TELEPHONE DIRECTORY SYSTEM
* PROCESS CODE : CCCCCCCC
* LAST NAME : XXXXXXXXXX
* FIRST NAME : XXXXXXXXXX
* EXTENSION# : N-NNN-NNNN
* INTERNAL ZIP : XXX/XXX
* CCCCCCCC = COMMAND
* ADD = INSERT ENTRY IN DB
* DELETE = DELETE ENTRY FROM DB
* UPDATE = UPDATE ENTRY FROM DB
* DISPLAY = DISPLAY ENTRY
* TADD = SAME AS ADD, BUT ALSO WRITE TO OPERATOR
* END = TERMINATE CONVERSATION
*
* CHANGES: THIS MODULE IS NEW IN IMS/ESA 3.2
* APAR... ID PREREQ. DATE.... DESCRIPTION...................
* KNQ0115 01 11/17/91 ADD COBOL LANG VERSION
© Copyright IBM Corp. 2001 339

*
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SOURCE-COMPUTER. IBM-370.
OBJECT-COMPUTER. IBM-370.
*
DATA DIVISION.
WORKING-STORAGE SECTION.
* DL/I FUNCTION CODES
77 GET-UNIQUE PICTURE X(4) VALUE ‘GU ‘.
77 GET-HOLD-UNIQUE PICTURE X(4) VALUE ‘GHU ‘.
77 GET-NEXT PICTURE X(4) VALUE ‘GN ‘.
77 GET-HOLD-NEXT PICTURE X(4) VALUE ‘GHN ‘.
77 DLET PICTURE X(4) VALUE ‘DLET’.
77 ISRT PICTURE X(4) VALUE ‘ISRT’.
77 REPL PICTURE X(4) VALUE ‘REPL’.
* DL/I CALL STATUS CODES
77 MESSAGE-EXIST PIC X(2) VALUE ‘CF’.
77 NO-MORE-SEGMENT PIC X(2) VALUE ‘QD’.
77 NO-MORE-MESSAGE PIC X(2) VALUE ‘QC’.
* MESSAGES
77 MDEL PICTURE X(40) VALUE
‘ENTRY WAS DELETED ‘.
77 MADD PICTURE X(40) VALUE
‘ENTRY WAS ADDED ‘.
77 MDIS PICTURE X(40) VALUE
‘ENTRY WAS DISPLAYED ‘.
77 MUPD PICTURE X(40) VALUE
‘ENTRY WAS UPDATED ‘.
77 MEND PICTURE X(40) VALUE
‘CONVERSATION HAS ENDED ‘.
77 MMORE PICTURE X(40) VALUE
‘DATA IS NOT ENOUGH. PLEASE KEY IN MORE ‘.
77 MINV PICTURE X(40) VALUE
‘PROCESS CODE IS NOT VALID ‘.
77 MNODATA PICTURE X(40) VALUE
‘NO DATA WAS INPUT. PLEASE KEY IN MORE ‘.
77 MNONAME PICTURE X(40) VALUE
‘LAST NAME WAS NOT SPECIFIED ‘.
77 MNOENT PICTURE X(40) VALUE
340 IMS Version 7 and Java Application Programming

‘SPECIFIED PERSON WAS NOT FOUND ‘.
77 MISRTE PICTURE X(40) VALUE
‘ADDITION OF ENTRY HAS FAILED ‘.
77 MDLETE PICTURE X(40) VALUE
‘DELETION OF ENTRY HAS FAILED ‘.
77 MREPLE PICTURE X(40) VALUE
‘UPDATE OF ENTRY HAS FAILED ‘.
* VARIABLES
77 SSA1 PICTURE X(9) VALUE ‘A1111111 ‘.
77 MODNAME PICTURE X(8) VALUE SPACES.
77 TRAN-CODE PICTURE X(8) VALUE ‘IVTCB’.
77 REPLY PICTURE X(16).
77 TEMP-ONE PICTURE X(8) VALUE SPACES.
77 TEMP-TWO PICTURE X(8) VALUE SPACES.
* DATA AREA FOR TERMINAL INPUT
01 INPUT-MSG.
02 IN-LL PICTURE S9(3) COMP.
02 IN-ZZ PICTURE S9(3) COMP.
02 IN-FILL PICTURE X(4).
02 IN-COMMAND PICTURE X(8).
02 TEMP-COMMAND REDEFINES IN-COMMAND.
04 TEMP-IOCMD PIC X(3).
04 TEMP-FILLER PIC X(5).
02 IN-LAST-NAME PICTURE X(10).
02 IN-FIRST-NAME PICTURE X(10).
02 IN-EXTENSION PICTURE X(10).
02 IN-ZIP-CODE PICTURE X(7).
* DATA AREA OUTPUT
01 OUTPUT-AREA.
02 OUT-LL PICTURE S9(3) COMP VALUE +95.
02 OUT-ZZ PICTURE S9(3) COMP VALUE +0.
02 OUTPUT-LINE PICTURE X(85) VALUE SPACES.
02 OUTPUT-DATA REDEFINES OUTPUT-LINE.
04 OUT-MESSAGE PIC X(40).
04 OUT-COMMAND PIC X(8).
04 OUT-DATA-TYPE.
06 OUT-LAST-NAME PIC X(10).
06 OUT-FIRST-NAME PIC X(10).
06 OUT-EXTENSION PIC X(10).
06 OUT-ZIP-CODE PIC X(7).
02 OUT-SEGMENT-NO PICTURE X(4) VALUE ‘0001’.
Appendix G. IVP application — COBOL source 341

* I/O AREA FOR DATA BASE HANDLING
01 IOAREA.
02 IO-LINE PICTURE X(37) VALUE SPACES.
02 IO-DATA REDEFINES IO-LINE.
04 IO-LAST-NAME PIC X(10).
04 IO-FIRST-NAME PIC X(10).
04 IO-EXTENSION PIC X(10).
04 IO-ZIP-CODE PIC X(7).
02 IO-FILLER PIC X(3) VALUE SPACES.
02 IO-COMMAND PIC X(8) VALUE SPACES.
* SCRATCH PAD AREA
01 SPA.
02 SPA-LL PICTURE X(2).
02 SPA-ZZ PICTURE X(4).
02 SPA-TRANCODE PICTURE X(8).
02 SPA-CALL PICTURE X(2).
02 SPA-COMMAND PICTURE X(8).
02 SPA-DATA.
04 SPA-LAST-NAME PIC X(10).
04 SPA-FIRST-NAME PIC X(10).
04 SPA-EXTENSION PIC X(10).
04 SPA-ZIP-CODE PIC X(7).
02 FILLER PICTURE X(19).
* DC TEXT FOR ERROR CALL
01 DC-TEXT.
02 TEXT1 PIC X(7) VALUE ‘STATUS ‘.
02 ERROR-STATUS PIC X(2).
02 TEXT2 PIC X(12) VALUE ‘DLI CALL = ‘.
02 ERROR-CALL PIC X(4).
* SEGMENT SEARCH ARGUMENT
01 SSA.
02 SEGMENT-NAME PIC X(8) VALUE ‘A1111111’.
02 SEG-KEY-NAME PIC X(11) VALUE ‘(A1111111 =’.
02 SSA-KEY PIC X(10).
02 FILLER PIC X VALUE ‘)’.
* FLAGS
01 FLAGS.
342 IMS Version 7 and Java Application Programming

02 SET-DATA-FLAG PIC X VALUE ‘0’.
88 NO-SET-DATA VALUE ‘1’.
02 TADD-FLAG PIC X VALUE ‘0’.
88 PROCESS-TADD VALUE ‘1’.
* COUNTERS
01 COUNTERS.
02 SPA-CALL-NO PIC 9(2) COMP VALUE 0.
02 L-SPACE-CTR PIC 9(2) COMP VALUE 0.
LINKAGE SECTION.
01 IOPCB.
02 LTERM-NAME PICTURE X(8).
02 FILLER PICTURE X(2).
02 TPSTATUS PICTURE XX.
02 FILLER PICTURE X(20).
01 DBPCB.
02 DBNAME PICTURE X(8).
02 SEG-LEVEL-NO PICTURE X(2).
02 DBSTATUS PICTURE XX.
02 FILLER PICTURE X(20).
PROCEDURE DIVISION USING IOPCB, DBPCB.
ON ENTRY IMS PASSES ADDRESSES FOR IOPCB AND DBPCB
MAIN-RTN.
MOVE GET-UNIQUE TO ERROR-CALL.
CALL ‘CBLTDLI’ USING GET-UNIQUE, IOPCB, SPA.
IF TPSTATUS = ‘ ‘ OR MESSAGE-EXIST
THEN
CALL ‘CBLTDLI’ USING GET-NEXT, IOPCB, INPUT-MSG
IF TPSTATUS = SPACES
THEN PERFORM PROCESS-INPUT THRU PROCESS-INPUT-END
ELSE IF TPSTATUS = NO-MORE-SEGMENT
THEN GOBACK
ELSE
MOVE GET-NEXT TO ERROR-CALL
PERFORM WRITE-DC-TEXT THRU WRITE-DC-TEXT-END
ELSE IF TPSTATUS = NO-MORE-MESSAGE
THEN GOBACK
ELSE PERFORM WRITE-DC-TEXT THRU WRITE-DC-TEXT-END.
GOBACK.
PROCEDURE PROCESS-INPUT
Appendix G. IVP application — COBOL source 343

PROCESS-INPUT.
IF IN-LL < 5
MOVE MNODATA TO OUT-MESSAGE
PERFORM TERM-ROUTINE THRU TERM-ROUTINE-END.
CHECK THE LEADING SPACE IN INPUT COMMAND AND TRIM IT OFF
INSPECT IN-COMMAND TALLYING L-SPACE-CTR FOR LEADING SPACE
REPLACING LEADING SPACE BY ‘*’.
IF L-SPACE-CTR > 0
UNSTRING IN-COMMAND DELIMITED BY ALL ‘*’ INTO TEMP-ONE
TEMP-TWO
MOVE TEMP-TWO TO IN-COMMAND
MOVE 0 TO L-SPACE-CTR
MOVE SPACES TO TEMP-TWO.
CHECK THE LEADING SPACE IN INPUT LAST NAME AND TRIM IT OFF
INSPECT IN-LAST-NAME TALLYING L-SPACE-CTR FOR LEADING
SPACE REPLACING LEADING SPACE BY ‘*’.
IF L-SPACE-CTR > 0
UNSTRING IN-LAST-NAME DELIMITED BY ALL ‘*’ INTO TEMP-ONE
TEMP-TWO
MOVE TEMP-TWO TO IN-LAST-NAME
MOVE 0 TO L-SPACE-CTR
MOVE SPACES TO TEMP-TWO.
* CHECK THE LEADING SPACE IN INPUT FIRST NAME AND TRIM IT OFF
INSPECT IN-FIRST-NAME TALLYING L-SPACE-CTR FOR LEADING
SPACE REPLACING LEADING SPACE BY ‘*’.
IF L-SPACE-CTR > 0
UNSTRING IN-FIRST-NAME DELIMITED BY ALL ‘*’ INTO TEMP-ONE
TEMP-TWO
MOVE TEMP-TWO TO IN-FIRST-NAME
MOVE 0 TO L-SPACE-CTR
MOVE SPACES TO TEMP-TWO.
* CHECK THE LEADING SPACE IN INPUT EXTENSION AND TRIM IT OFF
INSPECT IN-EXTENSION TALLYING L-SPACE-CTR FOR LEADING
SPACE REPLACING LEADING SPACE BY ‘*’.
IF L-SPACE-CTR > 0
UNSTRING IN-EXTENSION DELIMITED BY ALL ‘*’ INTO TEMP-ONE
TEMP-TWO
MOVE TEMP-TWO TO IN-EXTENSION
344 IMS Version 7 and Java Application Programming

*
MOVE 0 TO L-SPACE-CTR
MOVE SPACES TO TEMP-TWO.
CHECK THE LEADING SPACE IN INPUT ZIP CODE AND TRIM IT OFF
INSPECT IN-ZIP-CODE TALLYING L-SPACE-CTR FOR LEADING SPACE
REPLACING LEADING SPACE BY ‘*’.
IF L-SPACE-CTR > 0
UNSTRING IN-ZIP-CODE DELIMITED BY ALL ‘*’ INTO TEMP-ONE
TEMP-TWO
MOVE TEMP-TWO TO IN-ZIP-CODE
MOVE 0 TO L-SPACE-CTR
MOVE SPACES TO TEMP-TWO.
MOVE IN-LAST-NAME TO IO-LAST-NAME.
MOVE IN-COMMAND TO IO-COMMAND.
IF SPA-CALL-NO = 0
MOVE IN-LAST-NAME TO IO-LAST-NAME
MOVE IN-COMMAND TO IO-COMMAND
ELSE IF IN-LAST-NAME EQUAL SPACES
THEN MOVE SPA-LAST-NAME TO IO-LAST-NAME
ELSE MOVE IN-LAST-NAME TO IO-LAST-NAME.
IF IN-COMMAND EQUAL SPACES
MOVE SPA-COMMAND TO IO-COMMAND
ELSE
MOVE IN-COMMAND TO IO-COMMAND.
IF IO-COMMAND EQUAL SPACES
THEN MOVE MINV TO OUT-MESSAGE
PERFORM TERM-ROUTINE THRU TERM-ROUTINE-END
ELSE IF IO-LAST-NAME EQUAL SPACES AND TEMP-IOCMD NOT = ‘END’
THEN MOVE MNONAME TO OUT-MESSAGE
PERFORM TERM-ROUTINE THRU TERM-ROUTINE-END
ELSE IF TEMP-IOCMD EQUAL ‘ADD’
THEN PERFORM TO-ADD THRU TO-ADD-END
ELSE IF TEMP-IOCMD EQUAL ‘TAD’
THEN MOVE 1 TO TADD-FLAG
PERFORM TO-ADD THRU TO-ADD-END
ELSE IF TEMP-IOCMD EQUAL ‘UPD’
THEN PERFORM TO-UPD THRU TO-UPD-END
ELSE IF TEMP-IOCMD EQUAL ‘DEL’
THEN PERFORM TO-DEL THRU TO-DEL-END
ELSE IF TEMP-IOCMD EQUAL ‘DIS’
THEN PERFORM TO-DIS THRU TO-DIS-END
ELSE IF TEMP-IOCMD EQUAL ‘END’
THEN PERFORM TO-END THRU TO-END-END
Appendix G. IVP application — COBOL source 345

ELSE
MOVE MINV TO OUT-MESSAGE
PERFORM TERM-ROUTINE THRU TERM-ROUTINE-END.
PROCESS-INPUT-END.
EXIT.
* PROCEDURE TO-ADD : ADDITION REQUEST HANDLER
TO-ADD.
IF IO-LAST-NAME EQUAL SPA-LAST-NAME
THEN MOVE SPA-DATA TO IO-DATA.
IF IN-FIRST-NAME EQUAL SPACES OR
IN-EXTENSION EQUAL SPACES OR
IN-ZIP-CODE EQUAL SPACES
THEN
MOVE MMORE TO OUT-MESSAGE
PERFORM TERM-ROUTINE THRU TERM-ROUTINE-END
ELSE
MOVE IN-FIRST-NAME TO IO-FIRST-NAME
MOVE IN-EXTENSION TO IO-EXTENSION
MOVE IN-ZIP-CODE TO IO-ZIP-CODE
MOVE IO-DATA TO SPA-DATA
MOVE IO-DATA TO OUT-DATA-TYPE
MOVE IO-COMMAND TO OUT-COMMAND
PERFORM ISRT-DB THRU ISRT-DB-END.
TO-ADD-END.
EXIT.
* PROCEDURE TO-UPD : UPDATE REQUEST HANDLER
TO-UPD.
MOVE 0 TO SET-DATA-FLAG.
MOVE IO-LAST-NAME TO SSA-KEY.
PERFORM GET-HOLD-UNIQUE-DB THRU GET-HOLD-UNIQUE-DB-END.
IF DBSTATUS = SPACES
THEN
IF IN-FIRST-NAME NOT = SPACES
MOVE 1 TO SET-DATA-FLAG
MOVE IN-FIRST-NAME TO IO-FIRST-NAME
END-IF
IF IN-EXTENSION NOT = SPACES
MOVE 1 TO SET-DATA-FLAG
MOVE IN-EXTENSION TO IO-EXTENSION
END-IF
IF IN-ZIP-CODE NOT = SPACES
MOVE 1 TO SET-DATA-FLAG
MOVE IN-ZIP-CODE TO IO-ZIP-CODE
346 IMS Version 7 and Java Application Programming

END-IF
MOVE IO-DATA TO OUT-DATA-TYPE.
MOVE IO-COMMAND TO OUT-COMMAND.
IF NO-SET-DATA
THEN
PERFORM REPL-DB THRU REPL-DB-END
ELSE
MOVE MNODATA TO OUT-MESSAGE
PERFORM TERM-ROUTINE THRU TERM-ROUTINE-END.
TO-UPD-END.
EXIT.
* PROCEDURE TO-DEL : DELETE REQUEST HANDLER
TO-DEL.
MOVE IO-LAST-NAME TO SSA-KEY.
PERFORM GET-HOLD-UNIQUE-DB THRU GET-HOLD-UNIQUE-DB-END.
IF DBSTATUS = SPACES
THEN
MOVE IO-DATA TO OUT-DATA-TYPE
MOVE IO-COMMAND TO OUT-COMMAND
PERFORM DLET-DB THRU DLET-DB-END.
TO-DEL-END.
EXIT.
* PROCEDURE TO-DIS : DISPLAY REQUEST HANDLER
TO-DIS.
MOVE IO-LAST-NAME TO SSA-KEY.
PERFORM GET-UNIQUE-DB THRU GET-UNIQUE-DB-END.
IF DBSTATUS = SPACES
THEN
MOVE IO-DATA TO OUT-DATA-TYPE
MOVE IO-COMMAND TO OUT-COMMAND
MOVE MDIS TO OUT-MESSAGE
PERFORM TERM-ROUTINE THRU TERM-ROUTINE-END.
TO-DIS-END.
EXIT.
* PROCEDURE TO-END : END REQUEST HANDLER
TO-END.
MOVE SPACES TO SPA-TRANCODE.
MOVE MEND TO OUT-MESSAGE.
PERFORM TERM-ROUTINE THRU TERM-ROUTINE-END.
TO-END-END.
EXIT.
Appendix G. IVP application — COBOL source 347

* PROCEDURE ISRT-DB : DATA BASE SEGMENT INSERT REQUEST HANDLER
ISRT-DB.
MOVE ISRT TO ERROR-CALL.
CALL ‘CBLTDLI’ USING ISRT, DBPCB, IOAREA, SSA1.
IF DBSTATUS = SPACES
THEN
IF PROCESS-TADD
DISPLAY ‘INSERT IS DONE, REPLY’ UPON CONSOLE
ACCEPT REPLY FROM CONSOLE
MOVE 0 TO TADD-FLAG
END-IF
MOVE MADD TO OUT-MESSAGE
PERFORM TERM-ROUTINE THRU TERM-ROUTINE-END
ELSE
MOVE MISRTE TO OUT-MESSAGE
MOVE DBSTATUS TO ERROR-STATUS
PERFORM WRITE-DC-TEXT THRU WRITE-DC-TEXT-END
PERFORM TERM-ROUTINE THRU TERM-ROUTINE-END.
ISRT-DB-END.
EXIT.
* PROCEDURE GET-UNIQUE-DB
* DATA BASE SEGMENT GET-UNIQUE-DB REQUEST HANDLER
GET-UNIQUE-DB.
MOVE GET-UNIQUE TO ERROR-CALL.
CALL ‘CBLTDLI’ USING GET-UNIQUE, DBPCB, IOAREA, SSA.
IF DBSTATUS NOT = SPACES
THEN
MOVE MNOENT TO OUT-MESSAGE
MOVE DBSTATUS TO ERROR-STATUS
PERFORM WRITE-DC-TEXT THRU WRITE-DC-TEXT-END
PERFORM TERM-ROUTINE THRU TERM-ROUTINE-END.
GET-UNIQUE-DB-END.
EXIT.
* PROCEDURE GET-HOLD-UNIQUE-DB
* DATA BASE SEGMENT GET-HOLD-UNIQUE-DB REQUEST HANDLER
GET-HOLD-UNIQUE-DB.
MOVE GET-HOLD-UNIQUE TO ERROR-CALL.
CALL ‘CBLTDLI’ USING GET-HOLD-UNIQUE, DBPCB, IOAREA, SSA.
IF DBSTATUS NOT = SPACES
THEN
MOVE MNOENT TO OUT-MESSAGE
348 IMS Version 7 and Java Application Programming

MOVE DBSTATUS TO ERROR-STATUS
PERFORM WRITE-DC-TEXT THRU WRITE-DC-TEXT-END
PERFORM TERM-ROUTINE THRU TERM-ROUTINE-END.
GET-HOLD-UNIQUE-DB-END.
EXIT.
* PROCEDURE REPL-DB : DATA BASE SEGMENT REPLACE REQUEST HANDLER
REPL-DB.
MOVE REPL TO ERROR-CALL.
CALL ‘CBLTDLI’ USING REPL, DBPCB, IOAREA.
IF DBSTATUS = SPACES
THEN
MOVE MUPD TO OUT-MESSAGE
PERFORM TERM-ROUTINE THRU TERM-ROUTINE-END
ELSE
MOVE MREPLE TO OUT-MESSAGE
MOVE DBSTATUS TO ERROR-STATUS
PERFORM WRITE-DC-TEXT THRU WRITE-DC-TEXT-END
PERFORM TERM-ROUTINE THRU TERM-ROUTINE-END.
REPL-DB-END.
EXIT.
* PROCEDURE DLET-DB : DATA BASE SEGMENT DELETE REQUEST HANDLER
DLET-DB.
MOVE DLET TO ERROR-CALL.
CALL ‘CBLTDLI’ USING DLET, DBPCB, IOAREA.
IF DBSTATUS = SPACES
THEN
MOVE MDEL TO OUT-MESSAGE
PERFORM TERM-ROUTINE THRU TERM-ROUTINE-END
ELSE
MOVE MDLETE TO OUT-MESSAGE
MOVE DBSTATUS TO ERROR-STATUS
PERFORM WRITE-DC-TEXT THRU WRITE-DC-TEXT-END
PERFORM TERM-ROUTINE THRU TERM-ROUTINE-END.
DLET-DB-END.
EXIT.
* PROCEDURE TERM-ROUTINE : TERMINAL ROUTINE
TERM-ROUTINE.
MOVE SPACES TO MODNAME.
PERFORM INSERT-SPA THRU INSERT-SPA-END.
IF IN-COMMAND = ‘END’
MOVE TRAN-CODE TO MODNAME.
Appendix G. IVP application — COBOL source 349

PERFORM INSERT-IO THRU INSERT-IO-END.
TERM-ROUTINE-END.
EXIT.
* PROCEDURE INSERT-SPA : SPA INSERT FOR IOPCB REQUEST HANDLER
INSERT-SPA.
MOVE ISRT TO ERROR-CALL.
MOVE IO-DATA TO SPA-DATA.
MOVE IO-COMMAND TO SPA-COMMAND.
ADD 1 TO SPA-CALL-NO.
MOVE SPA-CALL-NO TO SPA-CALL.
CALL ‘CBLTDLI’ USING ISRT, IOPCB, SPA.
IF TPSTATUS NOT = SPACES
THEN PERFORM WRITE-DC-TEXT THRU WRITE-DC-TEXT-END.
INSERT-SPA-END.
EXIT.
* PROCEDURE INSERT-IO : INSERT FOR IOPCB REQUEST HANDLER
INSERT-IO.
MOVE ISRT TO ERROR-CALL.
IF MODNAME EQUAL SPACES
THEN
CALL ‘CBLTDLI’ USING ISRT, IOPCB, OUTPUT-AREA
ELSE
CALL ‘CBLTDLI’ USING ISRT, IOPCB, OUTPUT-AREA, MODNAME
MOVE SPACES TO MODNAME.
IF TPSTATUS NOT = SPACES
THEN PERFORM WRITE-DC-TEXT THRU WRITE-DC-TEXT-END.
INSERT-IO-END.
EXIT.
* PROCEDURE WRITE-DC-TEXT : WRITE ERROR STATUS CODE
WRITE-DC-TEXT.
MOVE TPSTATUS TO ERROR-STATUS.
DISPLAY DC-TEXT UPON CONSOLE.
WRITE-DC-TEXT-END.
EXIT.
350 IMS Version 7 and Java Application Programming

Appendix H. Installing the IVP Phone application
This appendix describes how to install the IVP Phone application.
H.1 Installation verification process
The following are example steps to verify an IMS Java install.
1. Set up your profile.imsjava as shown in Figure 124.
export IBMIMSJ_HOME=/usr/lpp/ims/imsjava71/classes.zip
export CLASSPATH=$CLASSPATH:$IBMIMSJ_HOME
#
echo ‘*------------------------------------------------------*
echo ‘ profile.imsjava executed ‘
echo ‘*------------------------------------------------------*
Figure 124. IMS Java profile sample
2. Set up your user profile.
3. Using OMVS foreground to compile and link the sample IVP:
a. Go to the directory that IMS Java is installed in: cd
usr/lpp/ims/imsjava71
b. Compile the IVP java programs: javac samples/ivp/*.java
4. Create the executable load module and put it in the IVP PGMLIB dataset
(which should be pre-allocated and should be a PDSE):
a. This can be done from OMVS, as shown in Figure 125.
hpj samples.ivp.IVP -main =samples.ivp.IVP \
-o="//'IVPEXEXX.PGMLIB(DFSIVP32)'" -alias=DFSIVP32 \
-target=IMS \
-leru opts="ENVAR(CLASSPATH=/usr/lpp/ims/imsjava7 :
/usr/lpp/ims/imsjava7 /imsjava.dll:/usr/lpp/hpj/lib" \
-exclude=com.ibm.ims.db.* \
-exclude =com.ibm.ims.application.* \
-exclude=com.ibm.ims.base.*
Figure 125. HPJ command to create executable load
© Copyright IBM Corp. 2001 351

. Or, it can be done using MVS BPXBATCH batch job, as shown in
Figure 126 and Figure 127.
//AUTOHPL JOB (@TS3,FA33),’ITSO IMS TEAM’,MSGCLASS=U,CLASS=A,
// NOTIFY=&SYSUID,TIME=1440,REGION=0M
/*JOBPARM S=SC47
//* TYPRUN=SCAN
//* ------------------------------------------------------------------
//* EXECUTE SCRIPT
//* ------------------------------------------------------------------
//UXCALL EXEC PGM=BPXBATCH,REGION=0M,
// PARM=’SH /u/imsres1/IVPhpj.ver1.standalone’ IVP script
//STEPLIB DD DISP=SHR,DSN=CEE.SCEERUN
//STDENV DD DUMMY
//STDIN DD DUMMY
//************************************* THE OUTPUT *********
//STDOUT DD PATH=’/u/imsres1/&SYSUID..autohpj.a082500.eout’,
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),PATHMODE=SIRWXU
//************************************* THE ERRORS *********
//STDERR DD PATH=’/u/imsres1/&SYSUID..autohpj.a082500.eerr’,
// PATHOPTS=(OWRONLY,OCREAT,OTRUNC),PATHMODE=SIRWXU
//************************************* THE SYSOUT *********
//SYSPRINT DD SYSOUT=*
//* ------------------------------------------------------------------
Figure 126. Sample MVS BPXBATCH JCL
352 IMS Version 7 and Java Application Programming

echo BEGIN IVPhpj.ver1.standalone
date
cd
cd /u/imsres1
. profile.imsjava
. profile.imsres1
cd
cd usr/lpp/hpj/bin
. profile.hpj
#
export IMSJAVA=/usr/lpp/ims/imsjava71
export IMSJDLL=/usr/lpp/ims/imsjava71/imsjava.jll
export IMSCLIB=/usr/lpp/ims/imsjava71/libJavTDLI.dll
export IMSHPJ=/usr/lpp/hpj/lib
export PATH=$PATH:/usr/lpp/hpj/bin
echo IMSJAVA : $IMSJAVA
echo IMSJDLL : $IMSJDLL
echo IMSCLIB : $IMSCLIB
echo IMSHPJ : $IMSHPJ
echo PATH : $PATH
#
cd
cd /u/imsres1/ims/imsjava71
javac samples/ivp/IVP.java -verbose
hpj samples.ivp.IVP \
-main=samples.ivp.IVP \
-o=”//’IMS.SJIMSR.IVP.PGMLIB(DFSIVP32)’” -alias=DFSIVP32 \
-target=IMS \
-lerunopts=”ENVAR(CLASSPATH=$IMSJAVA:$IMSJDLL:$IMSCLIB:$IMSHPJ” \
-verbose \
-include=samples.ivp.IVPDatabaseView \
-exclude=com.ibm.ims.db.* \
-exclude=com.ibm.ims.application.* \
-exclude=com.ibm.ims.base.*
echo END IVPhpj.ver1.standalone
Figure 127. Sample IVP BPXBATCH Script
5. Add the data set discussed above to the STEPLIB in the JCL that starts
the IMS MPR region or IMS BMP region. In the Installation Verification
Process, this data set must come before any other data set in the
STEPLIB concatenation.
STEPLIB DD DSN=IVPEXEXX.PGMLIB,DISP=SHR ==>> your program library
Appendix H. Installing the IVP Phone application 353

6. Also include the dataset for the IMS Java class libraries and HPJ class
libraries in the STEPLIB, as shown in Figure 128.
DD DSN=hlq.SDFSJLIB,DISP=SHR
DD DSN=VAJAVA.V3R0M0.SHPJMOD,DISP=SHR
DD DSN=VAJAVA.V3R0M0.SHPOMOD,DISP=SHR
Figure 128. Sample IMS Java class library and HPJ class libraries
The HLQ (High Level Qualifier) is the PDSE which you specified during the
installation process for IMS Java. You also need to change the Version
number of the HPJ to reflect the correct version of HPJ installed.
7. On your IMS MTO, issue the following IMS command:
/START IMSMSGx
or
/START IMSBMPx
The commands above are just examples where you have built your JCL
for Message Region (MPR) or Batch Message Region (BMP).
8. Go to the IMS terminal and invoke the formatted screen for the
transaction:
/format IVTCC
Note
If you receive a DFS057 , the modname IVTCC might reside in your
TFORMAT. Hence, issue the /TEST MFS first.
354 IMS Version 7 and Java Application Programming

9. An input screen like the one in Figure 129 will be displayed.
**************************************************
* IMS INSTALLATION VERIFICATION PROCEDURE *
**************************************************
Figure 129. IVTCC input screen
TRANSACTION TYPE : CONVERSATIONAL
DATE : 09/01/00
PROCESS CODE (*1) :
LAST NAME :
(*1) PROCESS CODE
ADD
DELETE
FIRST NAME : UPDATE
DISPLAY
EXTENSION NUMBER : TADD
END
INTERNAL ZIP CODE :
SEGMENT# :
The result of the IVTCC DISPLAY Query will be as shown in Figure 130 and
Figure 131.
Appendix H. Installing the IVP Phone application 355

Figure 130. IVTCC DISPLAY query
Figure 131. IVTCC DISPLAY output query
356 IMS Version 7 and Java Application Programming
**************************************************
* IMS INSTALLATION VERIFICATION PROCEDURE *
**************************************************
TRANSACTION TYPE : CONVERSATIONAL
DATE : 09/01/00
PROCESS CODE (*1) : display
LAST NAME : last1
(*1) PROCESS CODE
ADD
DELETE
FIRST NAME : UPDATE
DISPLAY
EXTENSION NUMBER : TADD
END
INTERNAL ZIP CODE :
**************************************************
* IMS INSTALLATION VERIFICATION PROCEDURE *
**************************************************
SEGMENT# :
TRANSACTION TYPE : CONVERSATIONAL
DATE : 09/01/00
PROCESS CODE (*1) :
LAST NAME : LAST1
(*1) PROCESS CODE
ADD
DELETE
FIRST NAME : FIRST1 UPDATE
DISPLAY
EXTENSION NUMBER : 8-111-1111 TADD
END
INTERNAL ZIP CODE : D01/R01
ENTRY WAS DISPLAYED SEGMENT# :

Appendix I. Dealership sample application
The dealership application mentioned throughout the book and the IMS Java
User’s Guide, SC27-0832-00 is outlined in detail in the following classes. This
application was created using JDBC for calls to the IMS database. The auto
dealership application contains the following methods:
AcceptOrder Accepts an order.
CancelOrder Cancels an order.
FindACar Search for a car currently in stock.
ListModels Lists all the models for every dealership.
RecordASale Records a sale.
ShowModelDetails Shows the details of a specific model.
The application was broken down into the following two packages:
- package dealership.database
- package dealership.application
The dealership.database package contains the following classes:
Dealer Maps the Dealer segment.
Model Maps the Model segment.
Order Maps the Order segment.
Sales Maps the Sales segment.
Stock Maps the Stock segment.
The dealership.application package contains the following classes:
DealerDatabaseView Maps the database view of all the segments.
IMSAuto The dealership application. It contains the
main() method.
InputMessage This is the default Input Message class. It
defines the fields in the input message to the
IMSAuto dealership application.
OutputMessage This is the default Output Message class. It
defines the fields in the output message to the
IMSAuto dealership application.
ErrorMessage The output message for error text.
AcceptOrderInput This is an Input Message class. It defines the
fields in the input message to the IMSAuto
dealership application used to accept a car
order.
© Copyright IBM Corp. 2001 357

I.1 Dealer class
OrderAccepted This is an Output Message class. It is the
result of an accepted order
CancelOrderInput This is an Input Message class. It defines the
fields in the input message to the IMSAuto
dealership application for cancelling an order.
Cancelled This is an Output Message class. It is the
message showing the results of cancelling an
order.
FindACarInput This is an Input Message class. It defines the
fields in the input message to the IMSAuto
dealership application to find a list of cars
based on given information.
CarFound This is an Output Message class. It contains
the results after the find a car request.
ListModelsInput This is an Input Message class. It defines the
fields in the input message to the IMSAuto
dealership application to list the cars in the
database.
ModelList This is an Output Message class. It contains
the list of models.
RecordASaleInput This is an Input Message class. It defines the
fields in the input message to the IMSAuto
dealership application specifying the
information of a car sale.
SalesRecord This is an Output Message class. It contains
the result of recording a sale.
ShowModelDetailsInput This is an Input Message class. It defines the
fields in the input message to the IMSAuto
dealership application requesting the details of
a specified car model.
ModelDetails This is an Output Message class. It contains
the results after a show details request.
package dealership.database;
import com.ibm.ims.db.*;
import com.ibm.ims.base.*;
358 IMS Version 7 and Java Application Programming

public class Dealer extends DLISegment {
}
I.2 Model class
static DLITypeInfo[] typeInfo = {
new DLITypeInfo(“DealerNumber”, DLITypeInfo.CHAR,
1, 4, “DLRNO”),
new DLITypeInfo(“DealerName”, DLITypeInfo.CHAR,
5, 30, “DLRNAME”),
new DLITypeInfo(“DealerAddress”, DLITypeInfo.CHAR,
35, 50),
new DLITypeInfo(“YTDSales”, “9(10)”, DLITypeInfo.ZONEDDECIMAL,
85, 10),
};
public Dealer() {
super(“DEALER”, typeInfo, 94);
}
package dealership.database;
import com.ibm.ims.db.*;
import com.ibm.ims.base.*;
public class Model extends DLISegment {
static DLITypeInfo[] typeInfo = {
new DLITypeInfo(“ModelTypeCode”, DLITypeInfo.CHAR,
1, 2, “MODTYPE”),
new DLITypeInfo(“CarMake”, DLITypeInfo.CHAR,
3, 10, “MAKE”),
new DLITypeInfo(“CarModel”, DLITypeInfo.CHAR,
13, 10, “MODEL”),
new DLITypeInfo(“CarYear”, DLITypeInfo.CHAR,
23, 4, “YEAR”),
new DLITypeInfo(“Price”, “99999”, DLITypeInfo.ZONEDDECIMAL,
27, 5, “MSRP”),
new DLITypeInfo(“EPACityMilage”, DLITypeInfo.CHAR,
32, 4),
new DLITypeInfo(“EPAHighwayMilage”, DLITypeInfo.CHAR,
36, 4),
new DLITypeInfo(“Horsepower”, DLITypeInfo.CHAR,
40, 4),
Appendix I. Dealership sample application 359

}
I.3 Order class
I.4 Sales class
};
public Model() {
super(“MODEL”, typeInfo, 43);
}
package dealership.database;
import com.ibm.ims.db.*;
import com.ibm.ims.base.*;
public class Order extends com.ibm.ims.db.DLISegment {
static DLITypeInfo[] typeInfo = {
new DLITypeInfo(“OrderNumber”, DLITypeInfo.CHAR,
1, 6, “ORDNBR”),
new DLITypeInfo(“Options”, DLITypeInfo.CHAR,
7, 30),
new DLITypeInfo(“Price”, “99999”, DLITypeInfo.ZONEDDECIMAL,
37, 5),
new DLITypeInfo(“OrderDate”, DLITypeInfo.CHAR,
42, 8),
new DLITypeInfo(“PurchaserLastName”, DLITypeInfo.CHAR,
50, 25, “LASTNME”),
new DLITypeInfo(“PurchaserFirstName”, DLITypeInfo.CHAR,
75, 25, “FIRSTNME”),
new DLITypeInfo(“SerialNo”, DLITypeInfo.CHAR,
100, 20),
new DLITypeInfo(“DeliverDate”, DLITypeInfo.CHAR,
120, 8)
};
// Constructor.
public Order() {
super(“ORDER”, typeInfo, 127);
}
}
package dealership.database;
import com.ibm.ims.db.*;
360 IMS Version 7 and Java Application Programming

I.5 Stock class
import com.ibm.ims.base.*;
public class Sales extends DLISegment {
static DLITypeInfo[] typeInfo = {
new DLITypeInfo(“DateSold”, DLITypeInfo.CHAR,
1, 8, “SALDATE”),
new DLITypeInfo(“PurchaserLastName”, DLITypeInfo.CHAR,
9, 25, “LASTNME”),
new DLITypeInfo(“PurchaserFirstName”, DLITypeInfo.CHAR,
34, 25, “FIRSTNME”),
new DLITypeInfo(“PurchaserAddress”, DLITypeInfo.CHAR,
59, 25),
new DLITypeInfo(“SoldBy”, DLITypeInfo.CHAR,
84, 10),
new DLITypeInfo(“StockVINumber”, DLITypeInfo.CHAR,
94, 20, “STKVIN”),
};
// Constructor.
public Sales() {
super(“SALES”, typeInfo, 113);
}
}
package dealership.database;
import com.ibm.ims.db.*;
import com.ibm.ims.base.*;
public class Stock extends DLISegment {
static DLITypeInfo[] typeInfo = {
new DLITypeInfo(“StockVINumber”, DLITypeInfo.CHAR,
1, 20, “STKVIN”),
new DLITypeInfo(“DateIn”, DLITypeInfo.CHAR,
21, 8),
new DLITypeInfo(“DateOut”, DLITypeInfo.CHAR,
29, 8),
new DLITypeInfo(“Color”, DLITypeInfo.CHAR,
37, 10, “COLOR”),
new DLITypeInfo(“Price”, “99999”, DLITypeInfo.ZONEDDECIMAL,
47, 5, “PRICE”),
new DLITypeInfo(“Lot”, DLITypeInfo.CHAR,
Appendix I. Dealership sample application 361

};
52, 10, “LOT”)
// Constructor.
public Stock() {
super(“STOCK”, typeInfo, 62);
}
}
I.6 DealerDatabaseView class
package dealership.application;
import com.ibm.ims.db.*;
import dealership.database.*;
// The Database view of the all the segments.
//
// Dealer
// |
// |
// |
// Model
// / | \
// / | \
// / | \
// / | \
// Order Sales Stock
public class DealerDatabaseView extends DLIDatabaseView {
static DLISegmentInfo[] segments = {
new DLISegmentInfo(new Dealer(), DLIDatabaseView.ROOT),
new DLISegmentInfo(new Model(), 0),
new DLISegmentInfo(new Order(), 1),
new DLISegmentInfo(new Sales(), 1),
new DLISegmentInfo(new Stock(), 1),
};
// Constructor.
public DealerDatabaseView() {
super(“DEALPCB1”, segments);
}
}
362 IMS Version 7 and Java Application Programming

I.7 IMSAuto class
package dealership.application;
/*
* Classname IMSAuto
* Version IMS 7.1
* Date 4/14/2000
*
*-------------------------------------------------------------------
*
* APPLICATION : IMS Java sample program,
*
*
* TRANSACTION : AUTOTRAN
*
* PSB : AUTOPSB
*
* DATABASE : DEALERDB
*
********************************************************************
*
*
* Licensed Materials - Contains Property of IBM
*
* (c) Copyright International Business Machines Corporation
* 2000 All Rights Reserved.
*
* U. S. GOVERNMENT RESTRICTED RIGHTS
*
* U.S. Government Users Restricted Rights - Use, duplication,
* or disclosure restricted by the GSA ADP Schedule Contract
* with the IBM Corporation.
*
* DISCLAIMER OF WARRANTIES. The following enclosed code is
* sample code created by IBM Corporation. This sample code is not
* part of any standard or IBM product and is provided to you
* solely for the purpose of assisting you in the development
* of your applications. The code is provided “AS IS”, without
* warranty of any kind. IBM shall not be liable for any damages
* arising out of your use of the sample code, even if they have
* been advised of the possibility of such damages.
*
*
* “Restricted Materials of IBM”
*
Appendix I. Dealership sample application 363

* 5655-B01 (C) Copyright IBM Corp. 2000
*
*
*/
import com.ibm.ims.base.*;
import com.ibm.ims.application.*;
import java.sql.*;
import java.io.*;
public class IMSAuto extends IMSApplication {
static {
try {
FileWriter fileWriter =
new FileWriter(“/tmp/imsauto_itso.trace”);
IMSTrace.setOutputWriter(fileWriter);
} catch (Exception e) {
IMSTrace.setOutputStream(System.err);
}
IMSTrace.libTraceLevel=IMSTrace.TRACE_DATA3;
IMSTrace.traceOn = true;
}
// The application connection to the database.
Connection connection = null;
/**
* Constructor.
*/
public IMSAuto() {
super();
}
/**
* This method is called when the user wants to accept an order.
* When a customer accepts an order, the car’s “SerialNo” and
delivery dates are filled in.
*
* This is an example of an UPDATE.
*/
public IMSFieldMessage acceptOrder(AcceptOrderInput inputMessage)
throws IMSException {
OrderAccepted orderAccepted = new OrderAccepted();
364 IMS Version 7 and Java Application Programming

}
// Get the input parameters for SQL statement from the input message.
String updateString = “UPDATE Order SET SerialNo = ‘”
+ inputMessage.getString(“StockVINumber”).trim() + “‘, “
+ “DeliverDate = ‘” + inputMessage.getString(“Date”).trim()
+ “‘ WHERE OrderNumber = ‘”
+ inputMessage.getString(“OrderNumber”).trim() + “‘”;
try {
Statement statement = connection.createStatement();
if (statement.executeUpdate(updateString) == 1) {
orderAccepted.setString(“ShortMessage”, “Order updated”);
} else {
IMSTransaction.getTransaction().rollback();
orderAccepted.setString(“ShortMessage”, “Update failed”);
}
} catch (SQLException e) {
return(reply (“Insert Failed:” + e.toString()));
}
return(orderAccepted);
/**
* Cancel an order.
*
* This is an example of a DELETE.
*/
public IMSFieldMessage cancelOrder(CancelOrderInput inputMessage)
throws IMSException {
Cancelled cancelled = new Cancelled();
// Start with the basic “DELETE” fot SQL statement.
StringBuffer queryString =
new StringBuffer(“DELETE FROM Order WHERE “);
// Get the input parameters from the input message.
// Note: that we must have both parameters passed in order to
// have a valid request.
String desiredOrder =
inputMessage.getString(“CancelOrderNumber”).trim();
String desiredDealer =
inputMessage.getString(“CancelDealerNumber”).trim();
// Do the update only if both parameters exist.
Appendix I. Dealership sample application 365

}
if (!desiredOrder.equals(““) && !desiredDealer.equals(““)) {
queryString.append(“OrderNumber = ‘” + desiredOrder + “‘”);
queryString.append(“ AND “);
queryString.append(“Dealer.DealerNumber = ‘”
+ desiredDealer + “‘”);
try {
Statement statement = connection.createStatement();
}
366 IMS Version 7 and Java Application Programming
}
// Do the delete - executeUpdate returns the number of orders
// that were deleted (execute SQL statement).
int results = statement.executeUpdate(queryString.toString());
// Return the number of delete orders to the user.
cancelled.setString(“Orders”, Integer.toString(results));
catch (SQLException e) {
return(reply (“Insert Failed:” + e.toString()));
}
// Invalid input - don’t do the request (return error message).
else {
cancelled.setString(“Orders”, “0”);
}
return(cancelled);
/**
* All IMS Java application logic is written by overriding
* the doBegin method. The doBegin method is called from the
* begin method.
*/
public void doBegin() throws IMSException {
// The IMS messageQueue.
IMSMessageQueue messageQueue = new IMSMessageQueue();
// The generic inputMessage.
InputMessage inputMessage = new InputMessage();
// Get the input messages in a loop.
// It processes these input messages until they are all processed.
//
// IMSMessageQueue.getUniqueMessage will check the status code and

eturns true if a message was retrieved and false if one was
// not. It throws IMSException for true errors.
//
// This application is started when the message queue has a message
// for it.
//
// This routine supports various types of input messages. It calls
// additional methods based on the type of input messages it
// received.
//
// Possible types of input messages are
// ListModelsInput
// ShowModelDetailsInput
// FindACarInput
// CancelOrderInput
// RecordASaleInput
// AcceptOrderInput
while (messageQueue.getUniqueMessage(inputMessage)) {
// Check to see if input was good and get CommandCode.
if (inputMessage.getMessageLength() > 0) {
// Get a connection using the DLI JDBC driver.
try {
Class.forName(“com.ibm.ims.db.DLIDriver”);
connection = DriverManager.getConnection
(“jdbc:dli:dealership.application.DealerDatabaseView”);
} catch (Exception e) {
messageQueue.insertMessage
(reply (“Connection not established”));
}
// Extract the commandCode.
String commandCode =
inputMessage.getString(“CommandCode”).trim();
// Do we really have a commandCode?
if (commandCode.length() > 0) {
// Determine which method to call and queue return results.
// The commandCode values will come into program in
// uppercase.
if (commandCode.equalsIgnoreCase(“listModels”)) {
messageQueue.insertMessage(listModels());
} else if (commandCode.equalsIgnoreCase(“findACar”)) {
messageQueue.insertMessage
(findACar(new FindACarInput(inputMessage)));
Appendix I. Dealership sample application 367

{
}
}
368 IMS Version 7 and Java Application Programming
} else if (commandCode.equalsIgnoreCase(“showModelDetails”))
messageQueue.insertMessage
(showModelDetails
(new ShowModelDetailsInput(inputMessage)));
} else if (commandCode.equalsIgnoreCase(“recordASale”)) {
messageQueue.insertMessage
(recordASale(new RecordASaleInput(inputMessage)));
} else if (commandCode.equalsIgnoreCase(“acceptOrder”)) {
messageQueue.insertMessage
(acceptOrder(new AcceptOrderInput(inputMessage)));
} else if (commandCode.equalsIgnoreCase(“cancelOrder”)) {
messageQueue.insertMessage
(cancelOrder(new CancelOrderInput(inputMessage)));
} else {
messageQueue.insertMessage
(reply (“UNKNOWN COMMAND CODE”));
}
// Clear out the inputMessage for next message in queue.
inputMessage.clearBody();
} else {
messageQueue.insertMessage(reply(“MISSING COMMAND CODE”));
}
} else {
messageQueue.insertMessage(reply (“INVALID INPUT”));
}
// Do a commit before we process next message.
IMSTransaction.getTransaction().commit();
/**
* Search for a car currently in stock at the dealership.
*
* This is an example of SELECT query where the fields of the resultset
* are specified. Note that path information is specified
* using the dot operator.
*
*/
public IMSFieldMessage findACar(FindACarInput inputMessage)
throws IMSException {
CarFound carFound = new CarFound();

Start building the SQL statement - update it as we find
// valid parameters.
String queryString = “SELECT Color, Lot, Dealer.DealerName,”
+ “ Model.CarMake, Model.CarModel,”
+ “ Model.CarYear FROM Stock”;
// Start creating the WHERE clause of SQL statement.
StringBuffer whereClause = new StringBuffer(“ WHERE “);
// Parameters is used to handle the “ AND “ in the SQL statement.
int parameters = 0;
// Updated the query for Make.
String desiredMake = inputMessage.getString(“Make”).trim();
if (!desiredMake.equals(““)) {
parameters++;
whereClause.append(“Model.CarMake = ‘” + desiredMake + “‘”);
}
// Updated the query for Model.
String desiredModel = inputMessage.getString(“Model”).trim();
if (!desiredModel.equals(““)) {
if (parameters > 0) {
whereClause.append(“ AND “);
}
parameters++;
whereClause.append(“Model.CarModel = ‘” + desiredModel + “‘”);
}
// Updated the query for Year.
String desiredYear = inputMessage.getString(“Year”).trim();
if (!desiredYear.equals(““)) {
if (parameters > 0) {
whereClause.append(“ AND “);
}
parameters++;
whereClause.append(“Model.CarYear = ‘” + desiredYear + “‘”);
}
// Updated the query for Color.
String desiredColor = inputMessage.getString(“Color”).trim();
if (!desiredColor.equals(““)) {
if (parameters > 0) {
whereClause.append(“ AND “);
}
parameters++;
Appendix I. Dealership sample application 369

}
370 IMS Version 7 and Java Application Programming
whereClause.append(“Color = ‘” + desiredColor + “‘”);
// Assume lowPrice is less than or equal to highPrice.
double lowPrice = inputMessage.getDouble(“LowPrice”);
double highPrice = inputMessage.getDouble(“HighPrice”);
// Ensure that all prices are not less then zero
if (lowPrice > 0) {
if (parameters > 0) {
whereClause.append(“ AND “);
}
parameters++;
}
// Note that this is the price from the Stock Segment.
whereClause.append(“Price > “ + lowPrice);
if (highPrice > 0) {
if (parameters > 0) {
whereClause.append(“ AND “);
}
parameters++;
}
// Note that this is the price from the Stock Segment.
whereClause.append(“Price < “ + highPrice);
// Append the where clause if needed.
if (parameters > 0) {
queryString = queryString + whereClause.toString();
}
// Do the query.
try {
Statement statement = connection.createStatement();
ResultSet results = statement.executeQuery(queryString);
// Counter to index through the carFound list.
int counter = 0;
// In loop, send back the result of the query as list
// since multiple cars may be returned.
while (results.next()) {
// Increase counter for next car found.
counter++;

}
}
carFound.setString(“Cars.” + counter +”.DealerName”,
results.getString(“DealerName”).trim());
carFound.setString(“Cars.” + counter +”.CarMake”,
results.getString(“CarMake”).trim());
carFound.setString(“Cars.” + counter +”.CarModel”,
results.getString(“CarModel”).trim());
carFound.setString(“Cars.” + counter +”.CarYear”,
results.getString(“CarYear”).trim());
carFound.setString(“Cars.” + counter +”.Lot”,
results.getString(“Lot”).trim());
carFound.setString(“Cars.” + counter +”.Price”,
results.getString(“Price”).trim());
// Check if any cars were found.
if (counter == 0) {
return(reply (“NO CAR FOUND”));
}
// Record the number of actual entries in the carFound message.
carFound.setInt(“Count”, counter);
} catch (SQLException e) {
return(reply (“Query Failed:” + e.toString()));
}
return(carFound);
/**
* List all of the models being sold by this dealership.
* This an example of a SELECT query a WHERE clause.
*/
public IMSFieldMessage listModels() throws IMSException {
ModelList modelList = new ModelList();
// Create the SQL statement - no inputs needed.
String queryString = “SELECT * FROM Model”;
// Do the query.
try {
Statement statement = connection.createStatement();
ResultSet results = statement.executeQuery(queryString);
// Counter to index through the carFound list.
int counter = 0;
Appendix I. Dealership sample application 371

}
372 IMS Version 7 and Java Application Programming
// In loop, send back the result of the query.
while (results.next()) {
counter++;
modelList.setString(“Cars.” + counter + “.ModelTypeCode”,
results.getString(“ModelTypeCode”).trim());
modelList.setString(“Cars.” + counter + “.CarMake”,
results.getString(“CarMake”).trim());
modelList.setString(“Cars.” + counter + “.CarModel”,
results.getString(“CarModel”).trim());
modelList.setString(“Cars.” + counter + “.CarYear”,
results.getString(“CarYear”).trim());
}
// Record the number of actual entries in the modelList message.
modelList.setInt(“Count”, counter);
} catch (SQLException e) {
return(reply (“Query Failed:” + e.toString()));
}
return(modelList);
/**
* Main.
*/
public static void main(String args []) {
}
IMSAuto imsauto = new IMSAuto();
// ‘begin’ is a method of the abstract base class, IMSApplication.
// It does initialization, calls doBegin, and does termination
// processing.
imsauto.begin();
/**
* This method is called when the user wants to record an sale.
* This is an example of INSERT. Note that the where clause is needed to
* specify the path. This is unique to IMS Java.
*/
public IMSFieldMessage recordASale(RecordASaleInput inputMessage)
throws IMSException {
SalesRecord salesRecord = new SalesRecord();

}
// Create the SQL statement.
String insertString = “INSERT INTO Sales “
+ “(DateSold, PurchaserLastName, PurchaserFirstName, “
+ “PurchaserAddress, SoldBy, StockVINumber) VALUES (‘”
+ inputMessage.getString(“Date”).trim() + “‘, ‘”
+ inputMessage.getString(“BuyerLastName”).trim() + “‘, ‘”
+ inputMessage.getString(“BuyerFirstName”).trim() + “‘, ‘”
+ inputMessage.getString(“BuyerAddress”).trim() + “‘, ‘”
+ inputMessage.getString(“SoldBy”).trim() + “‘, ‘”
+ inputMessage.getString(“StockVINumber”).trim() + “‘)”
+ “ WHERE Dealer.DealerNumber = ‘”
+ inputMessage.getString(“DealerNumber”).trim()
+ “‘ AND Model.ModelTypeCode = ‘”
+ inputMessage.getString(“ModelTypeCode”).trim() + “‘”;
// Do the query.
try {
Statement statement = connection.createStatement();
if (statement.executeUpdate(insertString) == 1) {
// Success.
salesRecord.setString(“ShortMessage”, “Sales recorded”);
} else {
// Failure.
IMSTransaction.getTransaction().rollback();
salesRecord.setString(“ShortMessage”, “Sales not accepted”);
}
} catch (SQLException e) {
return(reply (“Insert Failed:” + e.toString()));
}
return(salesRecord);
/**
* This method is called when to send reply with an error message.
*/
public IMSFieldMessage reply(String errmsg) throws IMSException {
ErrorMessage errorMessage = new ErrorMessage();
// Build an error message from a string.
errorMessage.setString(“MessageText”, errmsg);
Appendix I. Dealership sample application 373

}
return(errorMessage);
/**
* Show the details of a particular model - this command
* works with the listModels command for a “drill down”
* type of query.
*
* This is an example of a SELECT query with a WHERE clause.
*
*/
public IMSFieldMessage showModelDetails
(ShowModelDetailsInput inputMessage)
throws IMSException {
ModelDetails modelDetails = new ModelDetails();
// Build the SQL query.
String queryString = “SELECT * FROM Model WHERE ModelTypeCode = ‘”
+ inputMessage.getString(“ModelTypeCode”) +“‘”;
// Do the query.
try {
Statement statement = connection.createStatement();
ResultSet results = statement.executeQuery(queryString);
374 IMS Version 7 and Java Application Programming
// Send back the result of the query.
if (results.next()) {
modelDetails.setString(“CarMake”,
results.getString(“CarMake”).trim());
modelDetails.setString(“ModelTypeCode”,
results.getString(“ModelTypeCode”).trim());
modelDetails.setString(“CarModel”,
results.getString(“CarModel”).trim());
modelDetails.setString(“CarYear”,
results.getString(“CarYear”).trim());
modelDetails.setString(“Price”,
results.getString(“Price”).trim());
modelDetails.setString(“EPACityMilage”,
results.getString(“EPACityMilage”).trim());
modelDetails.setString(“EPAHighwayMilage”,
results.getString(“EPAHighwayMilage”).trim());
modelDetails.setString(“HorsePower”,
results.getString(“HorsePower”).trim());
} else {
return(reply (“UNKNOWN TYPE”));

I.8 InputMessage class
}
}
}
} catch (SQLException e) {
return(reply (“showModelDetails - Query Failed:” + e.toString()));
}
return(modelDetails);
package dealership.application;
import com.ibm.ims.base.*;
import com.ibm.ims.application.*;
/**
* This is the default Input Message class. It defines the
* fields in the input message to the IMSAuto dealership
* application.
*/
public class InputMessage extends IMSFieldMessage {
final static DLITypeInfo[] fieldInfo = {
new DLITypeInfo(“CommandCode”, DLITypeInfo.CHAR, 1, 20),
};
// Constructor.
public InputMessage() {
super(fieldInfo, 141, false);
}
}
I.9 OutputMessage class
package dealership.application;
import com.ibm.ims.db.*;
import com.ibm.ims.base.*;
import com.ibm.ims.application.*;
/**
* This is the Output Message class
*/
Appendix I. Dealership sample application 375

I.10 ErrorMessage class
public class OutputMessage extends IMSFieldMessage {
final static DLITypeInfo[] fieldInfo = {
// common field to identify the type of output messages
//
// possible values could be
// errormsg error messsages
// qmodrlts result of command code = qmodels
// canorlt result of command code = canorder
// roster result of command code = salestaff
new DLITypeInfo (“MessageType”, DLITypeInfo.CHAR, 1, 10),
}
// fields used for error message (errormsg)
new DLITypeInfo (“MessageText”, DLITypeInfo.CHAR, 11, 246),
// fields used to return results after a query models (qmodrlts)
new DLITypeInfo (“ModelType”, DLITypeInfo.CHAR, 11, 1),
new DLITypeInfo (“ModelColor”, DLITypeInfo.CHAR, 12, 10),
new DLITypeInfo (“Price”, DLITypeInfo.DOUBLE, 22, 8),
new DLITypeInfo (“Doors”, DLITypeInfo.INTEGER, 30, 4),
// fields used to return results of canceling a order (canorlt)
new DLITypeInfo (“Canceled”, DLITypeInfo.INTEGER, 11, 4),
new DLITypeInfo (“CancelMessage”, DLITypeInfo.CHAR, 15, 30),
// fields used to return results of query on sales staff roster)
new DLITypeInfo (“StaffSize”, DLITypeInfo.INTEGER, 11, 4),
};
public OutputMessage()
{
super(fieldInfo, 256, false);
}
package dealership.application;
import com.ibm.ims.base.*;
import com.ibm.ims.application.*;
/**
* Output message for error text.
*/
public class ErrorMessage extends IMSFieldMessage {
376 IMS Version 7 and Java Application Programming

final static DLITypeInfo[] fieldInfo = {
new DLITypeInfo (“MessageText”, DLITypeInfo.CHAR, 1, 80)
};
// Constructor.
public ErrorMessage() {
super(fieldInfo, 79, false);
}
}
I.11 AcceptOrderInput class
package dealership.application;
import com.ibm.ims.base.*;
import com.ibm.ims.application.*;
/**
* This is an Input Message class. It defines the fields in the
* input message to the IMSAuto dealership application used to
* accept a car order.
*/
public class AcceptOrderInput extends IMSFieldMessage {
final static DLITypeInfo[] fieldInfo = {
new DLITypeInfo(“CommandCode”, DLITypeInfo.CHAR, 1, 20),
new DLITypeInfo(“OrderNumber”, DLITypeInfo.CHAR, 21, 6),
new DLITypeInfo(“Date”, DLITypeInfo.CHAR, 27, 8),
new DLITypeInfo(“StockVINumber”, DLITypeInfo.CHAR, 35, 20),
};
// Constructor.
public AcceptOrderInput(InputMessage inputMessage) {
super(inputMessage, fieldInfo);
}
}
I.12 OrderAccepted class
package dealership.application;
import com.ibm.ims.base.*;
import com.ibm.ims.application.*;
/**
* Result of accepted order.
Appendix I. Dealership sample application 377

*/
public class OrderAccepted extends IMSFieldMessage {
final static DLITypeInfo[] fieldInfo = {
new DLITypeInfo (“ShortMessage”, DLITypeInfo.CHAR, 1, 80)
};
// Constructor.
public OrderAccepted() {
super(fieldInfo, 79, false);
}
}
I.13 CancelOrderInput class
I.14 Cancelled class
package dealership.application;
import com.ibm.ims.base.*;
import com.ibm.ims.application.*;
/**
* This is an Input Message class. It defines the fields in the
* input message to the IMSAuto dealership application for
* cancelling an order.
*/
public class CancelOrderInput extends IMSFieldMessage {
final static DLITypeInfo[] fieldInfo = {
new DLITypeInfo(“CommandCode”, DLITypeInfo.CHAR, 1, 20),
new DLITypeInfo(“CancelOrderNumber”, DLITypeInfo.CHAR, 21, 6),
new DLITypeInfo(“CancelDealerNumber”, DLITypeInfo.CHAR, 27, 4),
};
// Constructor.
public CancelOrderInput(InputMessage inputMessage) {
super(inputMessage, fieldInfo);
}
}
package dealership.application;
import com.ibm.ims.base.*;
import com.ibm.ims.application.*;
/**
378 IMS Version 7 and Java Application Programming

* Message showing the results of canceling a order
*/
public class Cancelled extends IMSFieldMessage {
final static DLITypeInfo[] fieldInfo = {
// Number of orders successfully deleted.
new DLITypeInfo (“Orders”, DLITypeInfo.CHAR, 1, 4)
};
// Constructor.
public Cancelled(){
super(fieldInfo, 34, false);
}
}
I.15 FindACarInput class
package dealership.application;
import com.ibm.ims.base.*;
import com.ibm.ims.application.*;
/**
* This is an Input Message class. It defines the fields in the
* input message to the IMSAuto dealership application to find a
* list of cars based on given information.
*/
public class FindACarInput extends IMSFieldMessage {
final static DLITypeInfo[] fieldInfo = {
new DLITypeInfo(“CommandCode”, DLITypeInfo.CHAR, 1, 20),
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.CHAR, 45, 5),
new DLITypeInfo(“HighPrice”, DLITypeInfo.CHAR, 50, 5),
new DLITypeInfo(“Color”, DLITypeInfo.CHAR, 55, 10),
};
// Constructor.
public FindACarInput(InputMessage inputMessage) {
super(inputMessage, fieldInfo);
}
}
Appendix I. Dealership sample application 379

I.16 Carfound class
package dealership.application;
import com.ibm.ims.base.*;
import com.ibm.ims.application.*;
/**
* Results after find a car request.
*/
public class CarFound extends IMSFieldMessage {
// This defines the fields needed to stored an individual car.
final static DLITypeInfo[] fieldInfo = {
new DLITypeInfo (“DealerName”, DLITypeInfo.CHAR, 1, 30),
new DLITypeInfo (“CarMake”, DLITypeInfo.CHAR, 31, 10),
new DLITypeInfo (“CarModel”, DLITypeInfo.CHAR, 41, 10),
new DLITypeInfo (“CarYear”, DLITypeInfo.CHAR, 51, 4),
new DLITypeInfo (“Lot”, DLITypeInfo.CHAR, 55, 10)
};
// This defines the fields needed to stored a list of 100 cars that are
// individually instantiated as “fieldInfo” defined above.
final static DLITypeInfo[] fieldListInfo = {
new DLITypeInfo (“Count”, DLITypeInfo.INTEGER, 1, 4),
new DLITypeInfoList (“Cars”, fieldInfo, 5, 64, 100),
};
// Constructor.
public CarFound() {
super(fieldListInfo, 6404, false);
}
}
I.17 ListModelsInput class
package dealership.application;
import com.ibm.ims.base.*;
import com.ibm.ims.application.*;
/**
* This is an Input Message class. It defines the fields in the
* input message to the IMSAuto dealership application to list
* the cars in the database.
*/
public class ListModelsInput extends IMSFieldMessage {
380 IMS Version 7 and Java Application Programming

I.18 ModelList class
final static DLITypeInfo[] fieldInfo = {
new DLITypeInfo(“CommandCode”, DLITypeInfo.CHAR, 1, 20),
};
// Constructor.
public ListModelsInput(InputMessage inputMessage) {
super(inputMessage, fieldInfo);
}
}
package dealership.application;
import com.ibm.ims.base.*;
import com.ibm.ims.application.*;
/**
* List of Models.
*/
public class ModelList extends IMSFieldMessage {
// This defines the fields needed to stored an individual car.
final static DLITypeInfo[] fieldInfo = {
new DLITypeInfo (“ModelTypeCode”, DLITypeInfo.CHAR, 1, 2),
new DLITypeInfo (“CarMake”, DLITypeInfo.CHAR, 3, 10),
new DLITypeInfo (“CarModel”, DLITypeInfo.CHAR, 13, 10),
new DLITypeInfo (“CarYear”, DLITypeInfo.CHAR, 23, 4)
};
// This defines the fields needed to stored a list of 100 cars that
// are individually instantiated as “DLITypeInfo[]” above.
final static DLITypeInfo[] fieldListInfo = {
new DLITypeInfo (“Count”, DLITypeInfo.INTEGER, 1, 4),
new DLITypeInfoList (“Cars”, fieldInfo, 5, 26, 100)
};
// Constructor.
public ModelList() {
super(fieldListInfo, 2604, false);
}
}
Appendix I. Dealership sample application 381

I.19 RecordASaleInput class
I.20 SalesRecord class
package dealership.application;
import com.ibm.ims.base.*;
import com.ibm.ims.application.*;
/**
* This is an Input Message class. It defines the fields in the
* input message to the IMSAuto dealership application specifying
* the information of a car sale.
*/
public class RecordASaleInput extends IMSFieldMessage {
final static DLITypeInfo[] fieldInfo = {
new DLITypeInfo(“CommandCode”, DLITypeInfo.CHAR, 1, 20),
new DLITypeInfo(“DealerNumber”, DLITypeInfo.CHAR, 21, 4),
new DLITypeInfo(“ModelTypeCode”, DLITypeInfo.CHAR, 25, 2),
new DLITypeInfo(“Date”, DLITypeInfo.CHAR, 27, 8),
new DLITypeInfo(“BuyerLastName”, DLITypeInfo.CHAR, 35, 25),
new DLITypeInfo(“BuyerFirstName”, DLITypeInfo.CHAR, 60, 25),
new DLITypeInfo(“BuyerAddress”, DLITypeInfo.CHAR, 85, 25),
new DLITypeInfo(“SoldBy”, DLITypeInfo.CHAR, 110, 10),
new DLITypeInfo(“StockVINumber”, DLITypeInfo.CHAR, 120, 20),
};
// Constructor.
public RecordASaleInput(InputMessage inputMessage) {
super(inputMessage, fieldInfo);
}
}
package dealership.application;
import com.ibm.ims.base.*;
import com.ibm.ims.application.*;
/**
* Result of recording a sale.
*/
public class SalesRecord extends IMSFieldMessage {
final static DLITypeInfo[] fieldInfo = {
new DLITypeInfo (“ShortMessage”, DLITypeInfo.CHAR, 21, 80)
};
382 IMS Version 7 and Java Application Programming

Constructor.
public SalesRecord() {
super(fieldInfo, 256, false);
}
}
I.21 ShowModelDetailsInput class
I.22 ModelDetails class
package dealership.application;
import com.ibm.ims.base.*;
import com.ibm.ims.application.*;
/**
* This is an Input Message class. It defines the fields in the
* input message to the IMSAuto dealership application requesting
* the details of a specified car model.
*/
public class ShowModelDetailsInput extends IMSFieldMessage {
final static DLITypeInfo[] fieldInfo = {
new DLITypeInfo(“CommandCode”, DLITypeInfo.CHAR, 1, 20),
new DLITypeInfo(“ModelTypeCode”, DLITypeInfo.CHAR, 21, 2),
};
// Constructor.
public ShowModelDetailsInput(InputMessage inputMessage) {
super(inputMessage, fieldInfo);
}
}
package dealership.application;
import com.ibm.ims.base.*;
import com.ibm.ims.application.*;
/**
* Results after show details request.
*/
public class ModelDetails extends IMSFieldMessage {
final static DLITypeInfo[] fieldInfo = {
new DLITypeInfo (“ModelTypeCode”, DLITypeInfo.CHAR,
1, 2),
new DLITypeInfo (“CarMake”, DLITypeInfo.CHAR,
Appendix I. Dealership sample application 383

3, 10),
new DLITypeInfo (“CarModel”, DLITypeInfo.CHAR,
13, 10),
new DLITypeInfo (“CarYear”, DLITypeInfo.CHAR,
23, 4),
new DLITypeInfo (“Price”, DLITypeInfo.ZONEDDECIMAL,
27, 5),
new DLITypeInfo (“Price”, DLITypeInfo.CHAR,
27, 5),
new DLITypeInfo (“EPACityMilage”, DLITypeInfo.CHAR,
32, 4),
new DLITypeInfo (“EPAHighwayMilage”, DLITypeInfo.CHAR,
36, 4),
new DLITypeInfo (“Horsepower”, DLITypeInfo.CHAR,
40, 4)
};
// Constructor.
public ModelDetails() {
super(fieldInfo, 43, false);
}
}
384 IMS Version 7 and Java Application Programming

Appendix J. Options for the hpj command
Table 6 outlines the options available for the hpj command on the OS/390.
Table 6. Options for the hpj command
Option Description Default
-- arg The double dash (--) option specifies
that any associated argument that
follows the double dash should be
treated as a filename, even if the
argument begins with a dash (-).
-architecture arch Generate optimized code for the
specified hardware architecture. This
option directs the compiler to only
generate code with machine instructions
that will run on the specified hardware
architecture.
-Boption Pass the specified linker option to the
linker. The valid linker options are both
linker-specific and operating
system-specific. Note that there cannot
be a space between the -B option and its
associated option.
-[no]c Specify -c to compile source or
bytecode files into object files without
linking. Specify -noc to compile source
or bytecode files into object files and to
link the objects into a load module.
-check args Controls whether normal Java run-time
checks are performed.
-classpath path Set the classpath to a specified path that
will be used to search for the Java
classes that you want to compile.
AIX: com
WIN: 486
© Copyright IBM Corp. 2001 385
-noc
-check all
Information
about the
defaults is
found in the
detailed
information for
this option.

Option Description Default
-[no]collapse [Do not] Put all object files and list files in
one directory. The default directory is the
current directory unless the -d option is
specified. The -collapse option is not
recommended if the -jlc option is
specified.
-[no]compact [Do not] Reduce code size at the
expense of execution speed. This option
has the following syntax:
386 IMS Version 7 and Java Application Programming
-compact | -nocompact
-d dir Deposit object and list files in the
specified directory and its
subdirectories, rather than in the
directory in which the source or class
files are found. If -d is not specified, the
object and list files are written to the
same location as their .class files. If the
-jlc option is specified, simple DLLs (.jlc
files) are deposited in the same location
as the object and list files. Related
information is found in the description for
the -[no]collapse option.
-encoding codepage Specify the encoding of any Java source
files. This option is similar to the
-encoding option of the JDK javac
command.
-exclude prefix Exclude all classes, packages, or sets of
packages from the compile that begin
with the specified prefix.
-nocollapse
-nocompact

Option Description Default
-exe Compile all classes into a single
executable. This is the default action
unless the -c, -jll, or -jlc option is
specified. If the Java executable is not
explicitly named with the -o option, the
executable is written to the current
directory under one of the following
default names (where filename is the
base name of the main class):
AIX: a.out
WIN: filename.exe
You may also want to explicitly name the
entry point for your executable by using
the -main option.
-[no]follow [Do not] Recursively compile all classes
that are referenced from those classes
initially supplied to the compiler.
-[no]g [Do not] Emit debugging information.
This option has the following syntax:
-g | -nog
Local variables are only visible if the
class file contains a LocalVariableTable
attribute. This means that your .java file
must be compiled with debug
information (for example, using javac
with the -g option). The
LocalVariableTable is an optional
attribute and there is no guarantee that
all Java source compilers generate it.
This is also true for the
LineNumberTable attribute and
SourceFileInfo attribute.
-[no]gui WIN: [Do Not] Suppress the DOS
window that normally appears when you
run an executable. This option has the
following syntax:
-gui | -nogui
-exe
-follow
-nog
-nogui
Appendix J. Options for the hpj command 387

Option Description Default
-help or -? If the hpj command is specified with
either the -help or -? option (and no
other options or arguments are
specified), usage information is
displayed for the hpj command.
-include prefix Include all classes, packages, or sets of
packages in the compile that begin with
the specified prefix.
-jlc Compile each class into a corresponding
simple DLL that has a .jlc extension.
388 IMS Version 7 and Java Application Programming
If the -main option is specified with the
-jlc option, the -main option is ignored
and a warning message is displayed.
Note that if you specify the -jlc option,
the -collapse option is not
recommended.
-jll Compile all classes into a single
compound DLL that has a .jll extension.
If -jll is specified and -c is not specified,
so that a link is performed, the -o option
must also be specified to name the DLL.
If the -main option is specified with the
-jll option, the -main option is ignored
and a warning message is displayed.
-[no]list [Do not] Produce an object code listing
file for each .class file. This option has
the following syntax:
-list | -nolist
When -list is specified, one listing file is
created for each class and is named
after the class. The listing files are
placed in the same location as the object
files. The -d and -collapse options
affect the naming and placement of
these files. Listing files have the
following extension:
AIX: .lst
WIN: .asm
-nolist

Option Description Default
-main classname Specify the base name of the class that
contains the main startup method to be
used in the building of a Java
executable. If -main is not specified, the
first class found during processing that
contains main() is used. This option is
not valid when -jll or -jlc is specified.
The classname is a fully qualified class
name, for example:
-main abc.staff.queryDB.queryMain
If -main is not specified when building a
Java executable, the system looks in all
the input files for a class with a main
method. When the first main method is
found, then its class is used as the entry
point for the executable. If a main
method is not found, the system
searches through the dependency list of
classes. If no main method is found, the
build is aborted and an error message is
displayed.
-[no]make [Do not] Rebuild out-of-date or missing
program objects when building Java
executables or DLLs.
If you specify -make, you cannot specify
the -partial option.
-maxmem size AIX: Restrict optimizations to a
maximum of size kilobytes of memory
storage. The range of valid entries is 1
to 2097151. Values of either 0 or
2097152 are equivalent to specifying
-nomaxmem.
-nomaxmem Use all available memory storage for
optimizations up to a maximum of
2147483647 bytes.
-nomake
2048
Appendix J. Options for the hpj command 389

Option Description Default
-o file Name of the executable file, compound
DLL (.jll), or simple DLL (.jlc). There is no
default name for compound DLLs, so
you must use the -o option when
building a compound DLL. Although you
can specify -o in conjunction with the
-jlc option, this is generally not
recommended.
390 IMS Version 7 and Java Application Programming
WIN: When building an executable, the
.exe extension is appended if the file
argument does not end in “.exe”.
-[no]O [Do not] Generate optimized code. This
option has the following syntax:
-O | -noO
Using -O will increase compile time and
may have greater storage requirements.
-partial prefix Compile only those classes that begin
with the specified prefix and, if the -c
option is not specified, rebuild the Java
executable or DLL. If you specify
-partial, you cannot specify -make.
-spill size AIX: Restrict the spill area to size bytes.
The -spill option defines the number of
bytes of stack space to reserve in each
subprogram, in case there are too many
variables to hold in registers and the
program needs temporary storage for
register contents.
When too many registers are in use, the
compiler stores the contents of some of
them into temporary storage called the
spill area. You may have to expand the
spill area; if so, you will receive a
compiler message telling you the size to
which you should increase the spill area.
Typically, you will only need to specify
this maximum spill area when compiling
very large programs with optimization.
Information
about the
default is found
in the detailed
information for
this option.
-noO
-spill 512

Option Description Default
-tune arch Generate optimized code for a particular
architecture to take advantage of such
architectural differences as the
scheduling of instructions.
-verbose Lists the .java files, .class files,
executables, and DLLs as they are
compiled.
AIX: pwr (if the
-architecture
option is
specified)
WIN: blend
Appendix J. Options for the hpj command 391

392 IMS Version 7 and Java Application Programming

Appendix K. Special notices
This publication is intended to help IMS system programmers and application
developers who plan to implement IMS Java in their IMS V7 environment.
The information in this publication is not intended to replace any of the IMS
Version or IMS Java publications. See the PUBLICATIONS section of the IBM
Programming Announcement for IMS Version 7. for more information about
what publications are considered to be product documentation.
References in this publication to IBM products, programs or services do not
imply that IBM intends to make these available in all countries in which IBM
operates. Any reference to an IBM product, program, or service is not
intended to state or imply that only IBM's product, program, or service may be
used. Any functionally equivalent program that does not infringe any of IBM's
intellectual property rights may be used instead of the IBM product, program
or service.
Information in this book was developed in conjunction with use of the
equipment specified, and is limited in application to those specific hardware
and software products and levels.
IBM may have patents or pending patent applications covering subject matter
in this document. The furnishing of this document does not give you any
license to these patents. You can send license inquiries, in writing, to the IBM
Director of Licensing, IBM Corporation, North Castle Drive, Armonk, NY
10504-1785.
Licensees of this program who wish to have information about it for the
purpose of enabling: (i) the exchange of information between independently
created programs and other programs (including this one) and (ii) the mutual
use of the information which has been exchanged, should contact IBM
Corporation, Dept. 600A, Mail Drop 1329, Somers, NY 10589 USA.
Such information may be available, subject to appropriate terms and
conditions, including in some cases, payment of a fee.
The information contained in this document has not been submitted to any
formal IBM test and is distributed AS IS. The use of this information or the
implementation of any of these techniques is a customer responsibility and
depends on the customer's ability to evaluate and integrate them into the
customer's operational environment. While each item may have been
reviewed by IBM for accuracy in a specific situation, there is no guarantee
that the same or similar results will be obtained elsewhere. Customers
© Copyright IBM Corp. 2001 393

attempting to adapt these techniques to their own environments do so at their
own risk.
Any pointers in this publication to external Web sites are provided for
convenience only and do not in any manner serve as an endorsement of
these Web sites.
The following terms are trademarks of the International Business Machines
Corporation in the United States and/or other countries:
IBM � Redbooks
Redbooks Logo
IAFP
AIX
AS/400
AT
CICS
CT
Current
DB2
DFSMS/MVS
Domino
Hummingbird
IBM
IMS/ESA
Language Environment
Lotus
Manage. Anything. Anywhere.
MVS/ESA
Netfinity
The following terms are trademarks of other companies:
Tivoli, Manage. Anything. Anywhere.,The Power To Manage., Anything.
Anywhere.,TME, NetView, Cross-Site, Tivoli Ready, Tivoli Certified, Planet
Tivoli, and Tivoli Enterprise are trademarks or registered trademarks of Tivoli
Systems Inc., an IBM company, in the United States, other countries, or both.
In Denmark, Tivoli is a trademark licensed from Kjøbenhavns Sommer - Tivoli
A/S.
C-bus is a trademark of Corollary, Inc. in the United States and/or other
countries.
Java and all Java-based trademarks and logos are trademarks or registered
trademarks of Sun Microsystems, Inc. in the United States and/or other
countries.
394 IMS Version 7 and Java Application Programming
OpenEdition
OS/2
OS/390
Parallel Sysplex
RACF
RS/6000
SAA
S/390
SP
System/36
System/360
System/390
VisualAge
VTAM
WebExplorer
WebSphere
XT
400

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of
Microsoft Corporation in the United States and/or other countries.
PC Direct is a trademark of Ziff Communications Company in the United
States and/or other countries and is used by IBM Corporation under license.
ActionMedia, LANDesk, MMX, Pentium and ProShare are trademarks of Intel
Corporation in the United States and/or other countries.
UNIX is a registered trademark in the United States and other countries
licensed exclusively through The Open Group.
SET, SET Secure Electronic Transaction, and the SET Logo are trademarks
owned by SET Secure Electronic Transaction LLC.
Other company, product, and service names may be trademarks or service
marks of others.
Appendix K. Special notices 395

396 IMS Version 7 and Java Application Programming

Appendix L. Related publications
L.1 IBM Redbooks
The publications listed in this section are considered particularly suitable for a
more detailed discussion of the topics covered in this redbook.
For information on ordering these publications see “How to get IBM
Redbooks” on page 401.
IMS e-business Connect Using the IMS Connectors, SG24-5427
IMS Primer, SG24-5352
L.2 IBM Redbooks collections
L.3 Other resources
Redbooks are also available on the following CD-ROMs. Click the CD-ROMs
button at ibm.com/redbooks for information about all the CD-ROMs offered,
updates and formats.
CD-ROM Title Collection Kit
Number
IBM System/390 Redbooks Collection SK2T-2177
IBM Networking Redbooks Collection SK2T-6022
IBM Transaction Processing and Data Management Redbooks Collection SK2T-8038
IBM Lotus Redbooks Collection SK2T-8039
Tivoli Redbooks Collection SK2T-8044
IBM AS/400 Redbooks Collection SK2T-2849
IBM Netfinity Hardware and Software Redbooks Collection SK2T-8046
IBM RS/6000 Redbooks Collection SK2T-8043
IBM Application Development Redbooks Collection SK2T-8037
IBM Enterprise Storage and Systems Management Solutions SK3T-3694
These publications are also relevant as further information sources:
IMS Administration Guide: Database Manager, SC26-9419
IMS Administration Guide: System, SC26-9420
IMS Administration Guide: Transaction Manager, SC26-9421
IMS Application Programming: Design Guide, SC26-9423
IMS Application Programming: EXEC DLI Commands for CICS and IMS,
SC26-9424
© Copyright IBM Corp. 2001 397

IMS Application Programming: Transaction Manager, SC26-9425
IMS Common Queue Server and Base Primitive Environment Guide and
Reference, SC26-9426
IMS Customization Guide, SC26-9427
IMS Database Recovery Control (DBRC) Guide and Reference,
SC26-9428
IMS Diagnosis Guide and Reference, LY37-3738
IMS Failure Analysis Structure Tables (FAST) for Dump Analysis,
LY37-3739
IMS Installation Volume 1: Installation and Verification, GC26-9429
IMS Installation Volume 2: System Definition and Tailoring, GC26-9430
IMS Licensed Program Specifications, GC26-9431
IMS Master Index, SC26-9432
IMS Message and Codes, GC26-9433
IMS Open Transaction Manager Access Guide, SC26-9434
IMS Operations Guide, SC26-9435
IMS Operator’s Reference, SC26-9436
IMS Release Planning Guide, GC26-9437
IMS Sample Operation Procedures, SC26-9438
IMS Summary of Operator Commands, SC26-9439
IMS Utilities Reference: Database and Transaction Manager, SC26-9440
IMS Utilities Reference: System, SC26-9441
IMS/ESA MRQ User’s Guide and Reference, SC26-8856
IMS/ESA Performance Analyzer Report Analysis, SC27-0705
IMS/ESA Performance Analyzer User’s Guide, SC26-9869
IMS Connect Guide and Reference, SC27-0946
398 IMS Version 7 and Java Application Programming

L.4 Referenced Web sites
These Web sites are also relevant as further information sources:
http://www.ibm.com/ IBM Home Page
http://www.redbooks.ibm.com/ ITSO Home Page
http://w3.itso.ibm.com IBM ITSO intranet Web site
http://www.elink.ibmlink.ibm.com/pbl/pbl Ordering IBM Redbooks
http://www.ibm.com/s390/java Java on the OS/390 platform
http://www.ibm.com/s390/java/javainst.html#prer
Download and install instructions: Java for OS/390 at JDK 1.1.8 level
http://www.ibm.com/s390/java/register.html Register to get Java code
Appendix L. Related publications 399

400 IMS Version 7 and Java Application Programming

How to get IBM Redbooks
This section explains how both customers and IBM employees can find out about IBM Redbooks,
redpieces, and CD-ROMs. A form for ordering books and CD-ROMs by fax or e-mail is also provided.
Redbooks Web Site ibm.com/redbooks
Search for, view, download, or order hardcopy/CD-ROM Redbooks from the Redbooks Web site.
Also read redpieces and download additional materials (code samples or diskette/CD-ROM images)
from this Redbooks site.
Redpieces are Redbooks in progress; not all Redbooks become redpieces and sometimes just a few
chapters will be published this way. The intent is to get the information out much quicker than the
formal publishing process allows.
E-mail Orders
Send orders by e-mail including information from the IBM Redbooks fax order form to:
In United States or Canada
Outside North America
Telephone Orders
United States (toll free)
Canada (toll free)
Outside North America
Fax Orders
United States (toll free)
Canada
Outside North America
e-mail address
pubscan@us.ibm.com
Contact information is in the “How to Order” section at this site:
http://www.elink.ibmlink.ibm.com/pbl/pbl
1-800-879-2755
1-800-IBM-4YOU
Country coordinator phone number is in the “How to Order”
section at this site:
http://www.elink.ibmlink.ibm.com/pbl/pbl
This information was current at the time of publication, but is continually subject to change. The latest
information may be found at the Redbooks Web site.
IBM Intranet for Employees
1-800-445-9269
1-403-267-4455
Fax phone number is in the “How to Order” section at this site:
http://www.elink.ibmlink.ibm.com/pbl/pbl
IBM employees may register for information on workshops, residencies, and Redbooks by accessing
the IBM Intranet Web site at http://w3.itso.ibm.com/ and clicking the ITSO Mailing List button.
Look in the Materials repository for workshops, presentations, papers, and Web pages developed
and written by the ITSO technical professionals; click the Additional Materials button. Employees
may access MyNews at http://w3.ibm.com/ for redbook, residency, and workshop announcements.
© Copyright IBM Corp. 2001 401

IBM Redbooks fax order form
Please send me the following:
Title Order Number Quantity
First name Last name
Company
Address
City Postal code
Telephone number Telefax number VAT number
Invoice to customer number
Credit card number
We accept American Express, Diners, Eurocard, Master Card, and Visa. Payment by credit card not
available in all countries. Signature mandatory for credit card payment.
402 IMS Version 7 and Java Application Programming
Country
Credit card expiration date Card issued to
Signature

Glossary
A
API. See application program interface.
applet. An applet is a piece of Java bytecode
that is executed on the workstation, under
control of the Web browser’s JavaVirtual
Machine. The applet is downloaded when the
browser accesses a page containing an
tag.
application. (1)Theusetowhichan
information processing system is put; for
example, a payroll application or an order-entry
application. (2) A collection of defined and
extended classes that provides a reusable piece
of functionality. An application contains and
organizes functionally related classes. It also
can contain subapplications and specify
prerequisites.
application program interface (API). An
architected functional interface supplied by an
operating system or other software system. The
interface enables an application program written
in a high-level language to use specific data or
functions of the underlying system.
ASCII. (American Standard Code for
Information Interchange), this is the world-wide
standard for the code numbers used by
computers to represent all the upper and
lower-case Latin letters, numbers, punctuation,
etc. There are 128 standard ASCII codes each
of which can be represented by a 7-digit binary
number, 0000000 through 1111111.
authority. Therighttodosomethingonthe
system or to use an object, such as a file or
document, in the system.
B
Base Primitive Environment (BPE). Asystem
service component that underlies the HWS
address space.
bit. (binary digit) A single digit number in base
2, in other words, either a 1 or a zero. The
smallest unit of computerized data. Bandwidth is
usually measured in bits per second. See also
bandwidth, bps, byte, kilobyte, megabyte.
browser. Software that enables users to browse
through the cyberspace of the World Wide Web.
SeealsoClient,URL,WWW.
byte. A set of bits that represent a single
character. Usually there are 8 bits in a byte,
sometimes more, depending on how the
measurement is being made.
© Copyright IBM Corp. 2001 403
C
client. A software program that is used to
contact and obtain data from a server software
program on another computer, often across a
great distance. Each client program is designed
to work with one or more specific kinds of server
programs, and each server requires a specific
kind of client. A Web browser is a specific kind
of client. See also browser, server.
client/server. The model of interaction in
distributed data processing in which a program
at one location sends a request to a program at
another location and awaits a response. The
requesting program is called a client, and the
answering program is called a server.
Common Gateway Interface. A standard
protocol through which a Web server can
execute programs running on the server
machine. CGI programs are executed in
response to requests from Web client browsers.
configuration. A description of a group of
components that identifies, for each component,
the component edition or version that is part of
the group.
D
database manager. other word for a database
management system.
datastore. An IMS TM system that provides
transaction and database processing.
domain name. The unique name that identifies
an Internet site. Domain names always have

two or more parts, separated by dots. The part on
the left is the most specific, and the part on the
right is the most general. A given machine may
have more than one domain name but a given
domain name points to only one machine.
Usually, all of the machines on a given network
will have the same thing as the right-hand portion
of their domain names, for example,
gateway.mynetwork.com.br,
mail.mynetwork.com.br, www.mynetwork.com.br,
and so on. It is also possible for a domain name
to exist but not be connected to an actual
machine. This is often done so that a group or
business can have an Internet e-mail address
without having to establish a real Internet site. In
these cases, some real Internet machine must
handle the mail on behalf of the listed domain
name. See also IP Number.
dynamic link library (DLL). A file containing
data and code objects that can be used by
programs or applications during loading or at run
timebutarenotpartoftheprogram’sexecutable (.EXE) file.
E
F
feature. A major component of a software
product that can be ordered separately.
field. A group of related bytes (such as name or
amount) that are treated as a unit in a record.
FTP. (File Transfer Protocol) The basic Internet
function that enables files to be transferred
between computers. You can use it to download
files from a remote, host computer, as well as to
upload files from your computer to a remote, host
computer. (See Anonymous FTP).
G
graphical user interface (GUI). Atypeof
interface that enables users to communicate with
a program by manipulating graphical elements
rather than by entering commands. Typically, a
graphical user interface includes a combination of
404 IMS Version 7 and Java Application Programming
graphics, pointing devices, menu bars,
overlapping windows, and icons.
H
host. (1) A computer that “hosts” outside
computer users by providing files, services or
sharing its resources. (2) Any computer on a
network that is a repository for services available
to other computers on the network. It is quite
common to have one host machine provide
several services, such as WWW and USENET.
See also Node, Network.
I
index. A set of pointers that are logically
arranged by the values of a key. Indexes provide
quick access and can enforce uniqueness on the
rows in a table.
IP. (Internet Protocol) The rules that provide basic
Internet functions. See TCP/IP.
IP Number. An Internet address that is a unique
number consisting of four parts separated by
dots, sometimes called a dotted quad. (For
example: 198.204.112.1). Every Internet
computer has an IP number and most computers
also have one or more domain names that are
plain language substitutes for the dotted quad.
J
Java. Java is a programming language invented
by Sun Microsystems that is specifically designed
for writing programs that can be safely
downloaded to your computer through the
Internet and immediately run without fear of
viruses or other harm to your computer or files.
Using small Java programs (called applets, Web
pages can include functions such as animations,
calculators, and other fancy tricks. We can expect
to see a huge variety of features added to the
Web using Java, since you can write a Java
program to do almost anything a regular
computer program can do, and then include that
Java program in a Web page.
Java Bytecode. The solution that the Java
system adopts to solve the binary distribution
problem is a "binary code format" that is

independent of hardware architectures, operating
system interfaces, and window systems. The
format of this system-independent binary code is
architecture neutral.
Java Classes. Aclassisasoftwareconstruct
that defines the data (state) and methods
(behavior) of the specific concrete objects that
are subsequently constructed from that class. In
Java terminology, a class is built out of members,
which are either fields or methods.
Java Packages. Java packages are collections
of classes and interfaces that are related to each
other in some useful way. Such classes need to
be able to access each other's instance variables
and methods directly.
K
L
LAN. Local area network. A computer network
located on a user’s establishment within a limited
geographical area. A LAN typically consists of
one or more server machines providing services
to a number of client workstations. See also
Ethernet.
Login. Theaccountnameusedtogainaccessto
a computer system. Not kept secret (unlike
password).
M
megabyte. A million bytes. A thousand kilobytes.
Seealsobyte,bit,kilobyte.
N
O
object-oriented programming. A programming
methodology built around objects and based on
sending messages back and forth between those
objects. The basic concepts of object-oriented
programming are encapsulation, inheritance, and
polymorphism.
P
parameter. A data element included as part of a
message to provide information that the object
might need. In Smalltalk, generally referred to as
an argument.
password. Acodeusedtogainaccesstoa
locked system. Good passwords contain letters
and nonletters and are not simple combinations.
PATH_INFO. A CGI variable, usually transmitted
to the CGI program in the form of an environment
variable. The PATH_INFO variable contains all
path information from the URL following the name
of the CGI executable. For a Web Connection
application, this information is the same as the
VisualAge part name.
Port. (1) A place where information goes into or
out of a computer, or both. For example, the
serial port on a personal computer is where a
modem would be connected. (2) On the Internet
port often refers to a number that is part of a
URL, appearing after a colon (:) right after the
domain name. Every service on an Internet
server listens on a particular port number on that
server. Most services have standard port
numbers; Web servers normally listen on port 80.
Services can also listen on nonstandard ports, in
which case the port number must be specified in
a URL when accessing the server. (3) Refers to
translating a piece of software to bring it from one
type of computer system to another. See also
domain name, server, URL. (4) In the case of
ITOC, HWS address space represents several
port numbers; each port will provide access to
one of a number of sockets associated with the
IMS Transaction Manager systems HWS is
connected to.
protocol. (1) The set of all messages to which an
object will respond. (2) Specification of the
structure and meaning (the semantics) of
messages that are exchanged between a client
and a server. (3) Computer rules that provide
uniform specifications so that computer hardware
and operating systems can communicate. It’s
similar to the way that mail, in countries around
the world, is addressed in the same basic format
so that postal workers know where to find the
recipient’s address, the sender’s return address
and the postage stamp. Regardless of the
405

underlying language, the basic protocols remain
the same.
R
record. A group of related data, fields, or words,
treated as a unit, such as name, address, and
telephone number.
repository. (1) An organized, shared body of
information that can support business and
data-processing activities.
return value. An object or data type that a
receiver object passes to a sender object in
response to a message.
S
script. A series of commands that define the
sequenceinwhichtheywillhavetobe
processed.
server. (1) A computer that provides services to
multiple users or workstations in a network; for
example, a file server, print server, or mail server.
(2) An object that performs one or more tasks on
behalf of a client. The server can be a computer
(a file server), a specific process on a server, or a
distributed object. A single server machine could
have several different server software packages
running on it, thus providing many different
serverstoclientsonthenetwork.Seealsoclient,
network.
service. A specific behavior that an object is
responsible for exhibiting.
servlet. A servlet is a piece of Java code that
runs inside a Java-enabled Web server, such as
the Lotus Domino Go Webserver Release 4.6.1or
IBM HTTP Server 1.3.3 with IBM WebSphere
Application Server V2.0, and extends the
functions of the server. The server hands
requests to the servlet, which replies to them.
Servlets are a good substitute for CGI programs
because they are faster and more easily
manageable.
session. A series of commands that come from
the same client and belong to the same logical
sequence and period. A session is identified by a
unique session key, which is generated by
406 IMS Version 7 and Java Application Programming
VisualAge. A session begins when a client
initially connects (without a session key) and
ends when a specified timeout period has
elapsed since the last connection.
structured query language (SQL). A language
used to access relational databases.
T
TCP/IP. (Transmission Control Protocol/Internet
Protocol) The basic programming foundation that
carries computer messages around the globe via
the Internet. The suite of protocols that defines
the Internet. Originally designed for the UNIX
operating system, TCP/IP software is now
available for every major kind of computer
operating system. To be truly on the Internet,
your computer must have TCP/IP software.
Telnet. An Internet protocol that lets you connect
your PC as a remote workstation to a host
computer anywhere in the world and to use that
computer as if you were logged on locally. You
often have the ability to use all of the software
and capability on the host computer, even if it’s a
huge mainframe.
U
uniform resource locator (URL). A standard
identifier for a resource on the World Wide Web,
used by a Web browser to initiate a connection.
The URL includes the communications protocol
to use, the name of the server, and path
information identifying the object to be retrieved
on the server. A URL looks like:
http://www.ibm.com, ortelnet://well.sf.ca.us.br, or
news:new.newusers.questions.br
V
variable. A storage place within an object for a
data element. The data element is an object,
such as a number or date, stored as an attribute
of the containing object.
W
Web Browser. As many other Internet facilities,
the Web uses a client-server processing model.
The Web browser is the client component.

Examples of Web browsers include Mosaic,
Netscape and the IBM WebExplorer. The Web
browser is responsible for formatting and
displaying information, interacting with the user
and invoking external viewers for data types that
it doesn’t support directly.
Web Server. Web servers are responsible for
servicing requests for information from Web
browsers. The information can be a file retrieved
from the servers local disk or generated by a
program called by the server to perform a specific
application function.
window. A rectangular area of the screen with
visible boundaries in which information is
displayed. Windows can overlap on the screen,
giving the appearance of one window being on
top of another.
World Wide Web. (WWW) (W3) (the Web) An
Internet client-server distributed information and
retrieval system based upon HTTP that transfers
hypertext documents across a varied array of
computer systems. The Web was created by the
CERN High-Energy Physics Laboratories in
Geneva, Switzerland in 1991. CERN boosted the
Web into international prominence on the
Internet.
407

408 IMS Version 7 and Java Application Programming

Abbreviations and acronyms
ACB Access Control Block
AIB Application Interface
Block
API Application Program
Interface
BIN BINary
BMP Batch Message
Processing Region
COBOL Common Business
Oriented Language
DB DataBase
DBD Database Descriptor
Block
DB2 DataBase 2
DD Data Definition JCL
statement
DLISAS Data Language I
Separate Address
Space
DLI See DL/1
DL/I Data Language 1
IBM International Business
Machines Corporation
IMS Information
Management System
IMS/ESA Information
Management
System/Enterprise
Systems Architecture
INTERNET a worldwide network of
TCP/IP-based networks
ITSO International Technical
Support Organization
ISO International
Organization for
Standardization
ITSO International Technical
Support Organization
JCL Job Control Language
(MVS and VSE)
MFS Message Format
Services
MPP Message Processing
Program
MPR Message Processing
Region
MVS Multiple Virtual Storage
(IBM System 370 &
390)
MVS/ESA Multiple Virtual
Storage/Enterprise
Systems Architecture
(IBM)
NT Microsoft Windows NT
OS/390 Operating System 390
PCB Program
Communication Block
PROC PROCedure
PROCLIB PROCedure LIBrary
(IBM System/360)
PSB Program Specification
Block
PTF Program Temporary Fix
RACF Resource Access
Control Facility
RBA Relative Byte Address
REXX Restructured Extended
eXecutor Language
SPA Scratch Pad Area
SSA Segment Search
Argument
TCPIP Transmission Control
Protocol / Internet
Protocol
© Copyright IBM Corp. 2001 409

TM Transaction Manager
TP Transaction
Program/process (OSI)
TSO Time Sharing Option
USERID USER IDentification
VTAM Virtual
Telecommunications
Access Method (IBM)
(runs
410 IMS Version 7 and Java Application Programming

Index
Symbols
/START IMSBMPx 354
/START IMSMSGx 354
A
abbreviations 409
Abends 305
AcceptOrderInput class 377
Accessing messages 46
ACID 7
acronyms 409
Adding trace statements 308
AIB 169
AIB interface 305
Alternate PCB program switching 10
API 9
APPLET 21
Applets 21
Application programming with DLIConnection 3
B
BPXBATCH 79, 83, 142
C
C 13, 23
C++ 13
CancelOrderInput class 378
Carfound class 380
CEEDUMP 163
CEETDLI interface 169
character-special files 74
Class libraries 18
Classes and field names 53
CLASSPATH 27
classpath path 89
COBOL 10, 23
COBOL code 70
com.ibm.ims.application 169
com.ibm.ims.base 169
Commit failure 305
connection to OS/390 30
Conversational transactions 3, 10
CORBA 11, 13
Creating a DLIConnection object 3
D
Data Link Library 23
DB2 V5 with APAR PQ19814 23
DBD Gen Input 149
DBPCB 169
Dealer Class 358
Dealer class 358
DealerDatabaseView class 362
dealership.application 357
dealership.database 357
debug tracing 160
Debugging 160
DEDB 10
DFSMS/MVS NFS 25
Diagnosing LE 163
Diagnosing problems 163
Directory structure 24
distributed client-server model 13
DL/I database 42, 52
DL/I ROLL 306
DLIConnection 42
DLIConnection access of databases 3
DLIConnection interface 70
DLIDatabaseView 44, 49
DLIException 299
DLIRecord 43
DLISegment 43, 44, 49
DLISegmentInfo 43, 51
DLITypeInfo 43, 52
DLITypeInfo objects 44
DLITypeInfoList 44
DLL 23
DLLs 104
Downloading the JDK 25
E
EBCDIC character data 39
editing your program 126
EEE floating point notation 14
enabling tracing 157
encapsulating data 8
eNetwork Communications Server facilities 23
Enterprise ToolKit 104
Enterprise Toolkit for OS/390 5
error management 161
ErrorMessage class 376
ET/390 5, 69, 119, 136
© Copyright IBM Corp. 2001 411

F
Fast Path databases 10
FindACarInput class 379
FTP 119
FTP client 23
FTP links 30
FTP server 23
Full-Function databases 10
Functional Recovery Routines 161
G
Get Unique 306
GUI Java 69
H
HALDB 10
Handling exceptions 161
HFS file system 71
HFS files 83
HIDAM 10
High availability large databases 10
High Performance Java 9
HPJ 9, 354
hpj command 104
HPJ compiler 26, 27, 69
HTML 9
HTML format 135
I
IBM Domino 9
IDL 13
Import 120
importing/exporting 126
IMS Auto Dealership 131
IMS Client for Java 8, 9, 151
IMS Connect 23
IMS Connector 151
IMS Java 3, 157
IMS Java Class Libraries 119
IMS Java install 351
IMS message queue 70
IMS message region 151
IMS MTO 354
IMS V7 393
IMS V7 Transaction Manager 23
IMS_Java_Classes 121
IMSAuto 131
412 IMS Version 7 and Java Application Programming
IMSAuto class 363
IMSAuto transaction 151
IMSErrorMessages 169
IMSJavaPGM 127
IMSTrace 157
Initiating IMSTracing 307
input LTERM 41
InputMessage class 313, 375
Installation verification 3
Installation Verification Program 316
IOPCB 169
ISHELL 73
ISPF menu 72
IVP Java programs 351
IVP PGMLIB 351
IVP Phone application 351
IVPDatabaseView class 312
J
Java API to IMS xvii
Java coding skills xvii
Java Database Connectivity 10
Java Development ToolKit 23
Java programmers 9
Java Run Time Library 26
Java sample tracing 160
Java Virtual Machine 11
java.awt, java.jfc 18
java.lang 18
java.lang.Thread 18
java.servlet 18
java.sql.CallableStatement 59
java.sql.Connection 57
java.sql.DatabaseMetaData 58
java.sql.Driver 58
java.sql.PreparedStatement 59
java.sql.ResultSet 58
java.sql.ResultSetMetaData 59
java.sql.Statement 58
JavaBean 19
javac compiler 70
JavaDevelopment Toolkit for OS/390 24
Javadoc HTML files 14
JAVADUMP 163
JavaToDLI 70
JavaToDLI example 3
JDBC 3, 10, 53
JDBC application 54

JDBC IMS 70
JDBC interface xvii
JDBC package 42
JDK 70, 71
JDK 1.1.1 for OS/390 16
JDK 1.1.4 16
JDK 1.1.8 24, 91
JIT compiler 17
JNI 10
JVM 11, 16
L
Language Environment 163
levels of tracing 160
LIBPATH 27
Logical relationships 10
M
Mapping 49
MFS 10
Model Class 359
ModelList class 381
MS Batch job 306
MS BMP 353
MS MPR 353
MS PDSE PGMLIB 71
MSApplication 169
MS-DOS prompt 29
MSFieldMessage 51, 169
MSMessageQueue 169
MSTransaction 169
Multi-segment messages 3, 10
multi-segment messages 42
MVS BPXBATCH 352
MVS Unix System Services 119
MVS USS HFS 138
N
Network Access Suite 28
NFS 119
NFS client 23, 28
NFS connections 28, 138
NFS server 23
non-conversational transactions 10
O
object server 7
OBROWSE 78, 86
OCOPY 87
ODBA 8
OEDIT 78, 86
OGET 88
OGETX 88
OMVS 81, 351
OO programming language 10
OpenEdition 8
OPUT 88
Order class 360
OS/390 LE V1 R7 23
OS/390 R2.6 23
OS/390 shell 5
OSHELL 79
OTMA 8, 9
output message 41
OutputMessage class 314, 375
P
PATH 27
PATHMODE 88
PCB 10
PDSE 23, 165
Performance Analyzer 6
PhoneBookSegment class 312
PL/1 23
POSIX 10
Prerequisites 28
problem detection 160
program argument 160
Programming Interfaces 70
Providing an array 3
PSB gen 49
PSB Gen Input 150
PSBGE 10
pseudoabends 305
R
RACF 74
RACF profile 74
RecordASaleInput class 382
Recoverable Resource Management Services 8
repeating structures 44
Required software 28
REXX 24
413

S
Sales class 360
Secondary indexes 10
setDefaultEncoding 39
ShowModelDetailsInput class 383
SmartGuide 121, 128
SNA 8
SPA 39
SPAMessage class 315
SQL 3
SQL92 query 53
SQLJ 10
SSA 43
SSAList 43
SSAList Object. 44
SSAQualificationStatement 43
Stock class 361
StringWriter 158
Subclassing DLIDatabaseView 46
Subclassing IMSSegment 3
T
Tar file 24
Tarball file 24
TCP/IP 8, 23
TFORMAT 354
thread synchronization 160
transaction code 42
TSO/E 71
TSO/E storage 28
U
UNIX System Services 26, 70
UNIX Systems Services 6
Use of AIB 165
V
VA-JAVA 131, 135
VAJAVA/390-DEBUG feature 25
Verifying the installation 25
Visual Age for Java 25
Visual Age for Java Enterprise Edition for OS/390
23
VisualAge for Java 5, 30, 69, 119
VTCC DISPLAY Query 355
414 IMS Version 7 and Java Application Programming
W
WebSphere Application Server 11
Windows NT 28, 30
Workbench 124
Workload Manager 6
Workstation environment 28

IBM Redbooks review
Your feedback is valued by the Redbook authors. In particular we are interested in situations where a
Redbook "made the difference" in a task or problem you encountered. Using one of the following
methods, please review the Redbook, addressing value, subject matter, structure, depth and
quality as appropriate.
Use the online Contact us review redbook form found at ibm.com/redbooks
Fax this form to: USA International Access Code + 1 914 432 8264
Send your comments in an Internet note to redbook@us.ibm.com
Document Number
Redbook Title
Review
What other subjects would you
like to see IBM Redbooks
address?
Please rate your overall
satisfaction:
Please identify yourself as
belonging to one of the
following groups:
Your email address:
The data you provide here may
be used to provide you with
information from IBM or our
business partners about our
products, services or activities.
Questions about IBM’s privacy
policy?
SG24-6123-00
IMS Version 7 and Java Application Programming
O Very Good O Good O Average O Poor
O Customer O Business Partner O Solution Developer
O IBM, Lotus or Tivoli Employee
O None of the above
O Please do not use the information collected here for future
marketing or promotional contacts or other communications beyond
the scope of this transaction.
The following link explains how we protect your personal information.
ibm.com/privacy/yourprivacy/
© Copyright IBM Corp. 2001 415

IMS Version 7 and Java Application Programming
(0.5” spine)
0.475”0.875”
250 459 pages

IMS Version 7 and Java
Application Programming
Learn to develop IMS
Java applications by
following examples
Create Java control
and execution
statements
Gain practical
experience in using
Java
This IBM Redbook is intended for customers who wish to
exploit the Java language support provided by IMS Version
7.1. Its prime audience are IMS and Java application
programmers, who can now use Java to develop IMS
application transactions, and IMS system programmers, who
support IMS applications development. This book will be
helpful to any organization that would like to access IMS
databases by using Java application programming.
As Java coding skills have become more readily available in
the IT employment marketplace, application development
with Java has become the de facto coding standard. This
book assumes a certain level of knowledge of IMS, Java, and
UNIX. It covers the base concepts of the Java environment,
the S/390 software and hardware requirements which enable
Java on the Enterprise platform, and how to download, install,
and configure the Java related application development
environment for your workstation, IMS/ESA, and OS/390.
We discuss two IMS applications that were developed within
IBM, using the Java API to IMS. The Telephone Directory IVP
application uses the Java Native DL/I interface, and the IMS
Auto Dealership application employs the JDBC interface from
Java to IMS. We also provide guidance on debugging,
problem determination, and some of the development
limitations you may encounter.
SG24-6123-00 ISBN 0738418277
INTERNATIONAL
TECHNICAL
SUPPORT
ORGANIZATION
®
BUILDING TECHNICAL
INFORMATION BASED ON
PRACTICAL EXPERIENCE
IBM Redbooks are developed by
the IBM International Technical
Support Organization. Experts
from IBM, Customers and
Partners from around the world
create timely technical
information based on realistic
scenarios. Specific
recommendations are provided
to help you implement IT
solutions more effectively in
your environment.
For more information:
ibm.com/redbooks