Documenti di Didattica
Documenti di Professioni
Documenti di Cultura
SC27-0832-02
IMS Version 7
SC27-0832-02
Note
Before using this information and the product it supports, be sure to read the general information under “Notices”.
Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
| Prerequisite Knowledge . . . . . . . . . . . . . . . . . . . . . . xv
| Change Indicators . . . . . . . . . . . . . . . . . . . . . . . . xv
Contents v
| DLISegment Example . . . . . . . . . . . . . . . . . . . . . 103
Bibliography . . . . . . . . . . . . . . . . . . . . . . . . . 111
IMS Version 7 Library . . . . . . . . . . . . . . . . . . . . . . 111
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
IBM may have patents or pending patent applications covering subject matter
described in this document. The furnishing of this document does not give you any
license to these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
For license inquiries regarding double-byte (DBCS) information, contact the IBM
Intellectual Property Department in your country or send inquiries, in writing, to:
IBM World Trade Asia Corporation
Licensing
2-31 Roppongi 3-chome, Minato-ku
Tokyo 106, Japan
The following paragraph does not apply to the United Kingdom or any other
country where such provisions are inconsistent with local law:
INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
PUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS
OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A
PARTICULAR PURPOSE. Some states do not allow disclaimer of express or
implied warranties in certain transactions, therefore, this statement may not apply to
you.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those
Web sites. The materials at those Web sites are not part of the materials for this
IBM product and use of those Web sites is at your own risk.
IBM may use or distribute any of the information you supply in any way it believes
appropriate without incurring any obligation to you.
Licensees of this program who wish to have information about it for the purpose of
enabling: (i) the exchange of information between independently created programs
The licensed program described in this information and all licensed material
available for it are provided by IBM under terms of the IBM Customer Agreement,
IBM International Program License Agreement, or any equivalent agreement
between us.
Information concerning non-IBM products was obtained from the suppliers of those
products, their published announcements or other publicly available sources. IBM
has not tested those products and cannot confirm the accuracy of performance,
compatibility or any other claims related to non-IBM products. Questions on the
capabilities of non-IBM products should be addressed to the suppliers of those
products.
All statements regarding IBM’s future direction or intent are subject to change or
withdrawal without notice, and represent goals and objectives only.
This information is for planning purposes only. The information herein is subject to
change before the products described become available.
This information contains examples of data and reports used in daily business
operations. To illustrate them as completely as possible, the examples include the
names of individuals, companies, brands, and products. All of these names are
fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
© (your company name) (year). Portions of this code are derived from IBM Corp.
Sample Programs. © Copyright IBM Corp. _enter the year or years_. All rights
reserved.
If you are viewing this information softcopy, the photographs and color illustrations
may not appear.
Trademarks
The following terms are trademarks of the IBM Corporation in the United States or
other countries or both:
BookManager MVS
DB2 OS/390
CICS WebSphere
IBM z/OS
IMS
Java and all Java-based trademarks and logos are trademarks of Sun
Microsystems, Inc., in the United States, other countries, or both.
UNIX is a registered trademark of The Open Group in the United States and other
countries.
Other company, product, and service names may be trademarks or service marks
of others.
Notices xiii
xiv IMS Java User’s Guide
Preface
| This book explains how to configure your system for IMS Java application support,
| how to build IMS Java metadata classes using the DLIModel utility, and how to
| write Java application programs that access IMS databases.
This softcopy book is available only in PDF and BookManager formats. This book is
available on the IMS Version 7 Licensed Product Kit (LK3T-3526). You can also get
the most current versions of the PDF and BookManager formats by going to the
IMS Web site at www.ibm.com/ims and linking to the Library page.
| Prerequisite Knowledge
| To configure your system for IMS Java, you must understand system administration
| for your system (IMS, WebSphere Application Server, CICS, or DB2). For IMS
| system administration, you should know the concepts in IMS Version 7
| Administration Guide: System.
| To create IMS Java metadata classes, which is a required step in writing IMS Java
| applications, you must understand IMS databases. IMS database concepts are
| described in IMS Version 7 Administration Guide: Database Manager.
| To write IMS Java applications, you must thoroughly understand the Java language
| and JDBC. This book assumes that you know Java and JDBC. It does not explain
| any Java or JDBC concepts.
| Change Indicators
| Technical changes are indicated in this publication by a vertical bar ( | ) to the left of
| the changed text.
| This book contains new information about the following enhancements to IMS Java
| application support:
| v JMP and JBP IMS dependent regions for a Java Virtual Machine (JVM)
| environment
| v DLIModel utility for creating IMS Java metadata classes
| v WebSphere Application Server for OS/390 and z/OS, CICS Transaction Server
| z/OS, and DB2 UDB for z/OS and OS/390 Stored Procedures support
|
| Library Changes for IMS Version 7
| The major change to the IMS Version 7 library is that it is available not only in
| hardcopy and in softcopy on BookManager, but also in softcopy Portable Document
| Format (PDF). The complete library is available in BookManager and PDF on the
| IMS Version 7 product kit CD-ROM (LK3T-3526). The unlicensed IMS Version 7
| softcopy library is available on the Transaction Processing and Data CD-ROM
| (SK2T-0730) and the OS/390 Collection CD-ROM (SK2T-6700) in BookManager.
| The unlicensed IMS Version 7 softcopy library is available in BookManager and
| PDF on the Web at http://www.ibm.com/ims
| The library includes a new book: IMS Version 7 IMS Java User’s Guide (IJUG). As
| a new book, the IJUG is available only in PDF and BookManager softcopy on the
| product kit (LK3T-3526) and on the Web at: http://www.ibm.com/ims
| IMS Java application programs use JDBC or the IMS Java hierarchic database
| interface. JDBC is the SQL-based standard interface for data access in the Java 2
| SDK Standard Edition and Enterprise Edition. IMS Java’s implementation of JDBC
| supports a selected subset of the full facilities of the JDBC 2.0 API. The IMS Java
| hierarchic database interface is more closely related to the standard DL/I database
| call interface used with other languages, and provides a lower-level access to IMS
| database functions than the JDBC interface.
| IMS Java provides class libraries that allow you to easily develop applications that
| can access IMS’s broad range of database types and options, including:
| v Full function databases
| v High Availability Large Databases (HALDBs)
| v Fast Path Data Entry Databases (DEDBs)
| v Logical relationships
| v Secondary indexes
| Regardless of what environment the IMS Java application runs in, it accesses the
| IMS databases the same way.
|
| Design Process
| 1. Determine what database information the application needs to process.
| 2. Create the IMS Java metadata classes based on the PSB using the DLIModel
| utility.
| The IMS database administrator, in addition to generating the PSB, also runs
| the DLIModel utility to create the IMS Java Metadata classes for the Java
| application developer to use to write the application program.
| 3. Write the application program. The DLIModel Java Report, generated by the
| DLIModel utility, provides the information about the IMS database.
| 4. Configure environment and deploy application.
|
| IMS Environment Overview
| IMS Java application programs run in one of two IMS dependent regions, which
| provide a Java Virtual Machine (JVM) environment for the Java applications:
| Restrictions:
| v IMS Java applications cannot run in an IMS batch environment.
| v JBPs cannot be message driven.
| Related Reading:
| v For guidance information on designing an IMS application, see IMS Version 7
| Application Programming: Design Guide.
| v For information on configuring JMP and JBP regions, see “IMS Setup” on page 4
| and IMS Version 7 Installation Volume 2: System Definition and Tailoring.
|
| WebSphere for z/OS Environment Overview
| You can write IMS Java applications that run on a WebSphere Application Server
| for z/OS and OS/390 J2EE server and access IMS databases. When WebSphere
| for z/OS and IMS DB are on the same operating system image, the IMS Java
| application—a WebSphere for z/OS Enterprise Java Bean (EJB)—accesses IMS
| databases using the Open Database Access (ODBA) interface.
| Related Reading: For information on configuring WebSphere for z/OS to run IMS
| Java applications, see “WebSphere for z/OS Setup” on page 8.
|
| CICS Environment Overview
| You can write IMS Java applications that run on CICS Transaction Server for z/OS
| and access IMS databases.
| Related Reading:
| v For information on configuring CICS to runs IMS Java applications, see “CICS
| Setup” on page 13.
| v For information on developing an IMS Java application that runs on a CICS
| Transaction Server, see “CICS Applications” on page 59.
|
| DB2 Environment Overview
| You can write DB2 UDB for z/OS and OS/390 Stored Procedures that access IMS
| databases.
| Related Reading:
| v For information on configuring DB2 to run IMS Java applications, see “DB2
| Setup” on page 15.
| v For information on developing an IMS Java application that runs as a DB2 stored
| procedure, see “DB2 Stored Procedures” on page 59.
| In this chapter:
| v “System Requirements for All Environments”
| v “General Restrictions”
| v “IMS Setup” on page 4
| v “WebSphere for z/OS Setup” on page 8
| v “CICS Setup” on page 13
| v “DB2 Setup” on page 15
| v “DLIModel Utility Setup” on page 19
|
| System Requirements for All Environments
| To use IMS Java to write application programs that access IMS databases, the
| following software is required:
| v IBM Developer Kit for OS/390, Java 2 Technology Edition with the Persistent
| Reusable Java Virtual Machine
| v OS/390 Version 2 Release 10 or higher
| v UNIX System Services available at runtime
| v Hierarchic File System (HFS) on operating system (For information on preparing
| HFS, see OS/390: Unix System Services File System Interface Reference)
| An IMS Java application may use path calls to access hierarchic paths of
| segments. Therefore, your PSBs may need to specify the P processing option for
| some or all segments. See Chapter 3, “Accessing an IMS Database” on page 23 for
| more information.
| IMS does not support local transactions. Therefore, the commit, rollback, and
| setAutoCommit methods on an IMS Java JDBC Connection object are not
| supported and throw an SQLException.
| IMS Restrictions
| JMP and JBP applications must be single threaded.
| IMS Configuration
| This section gives the steps to configure JMP and JBP IMS Java dependent
| regions.
| Related Reading:
| v For detailed information on DFSJBP and DFSJMP procedures, used to start JVM
| dependent regions, see IMS Version 7 Installation Volume 2: System Definition
| and Tailoring.
| v For details about master JVMs and worker JVMs, and for a complete list of
| possible JVM options, see IBM Developer Kit for OS/390, Java 2 Technology
| Edition: New IBM Technology featuring Persistent Reusable Java Virtual
| Machines.
| /usr/lpp/ims/imsjava71 contains the native library code for IMS Java, such as
| libJavTDLI.so
| v DFSJVMMS
| -Dibm.jvm.shareable.application.class.path=>
| /usr/lpp/ims/imsjava71/samples.jar
| -Dibm.jvm.trusted.middleware.class.path=>
| /usr/lpp/ims/imsjava71/imsjava.jar
| -Xinitacsh128k
| -Xinitsh128k
| -Xmaxf0.6
| -Xminf0.3
| -Xmx64M
| -Xoss400k
| v DFSJVMWK
| -Xmaxf0.6
| -Xminf0.3
| -Xmx64M
| -Xoss400k
| 3. Create HFS files JVM.out and JVM.err in the directory.
| 4. Submit the JCL stream to start a JMP (Java Message Processing) region. The
| JCL must contain the following:
| v Four IMS.PROCLIB members defined in step 2
| v JAVAOUT and JAVAERR DD statements to allow standard output and
| standard errors to be sent to a file. For example:
| //JAVAOUT DD PATH=’/myApplication/JVM.out’
| //JAVAERR DD PATH=’/myApplication/JVM.err’
| Important: This procedure fails if the HFS files JVM.out and JVM.err do not
| exist in the specified directory.
| 5. From the IMS terminal, invoke the formatted screen for the transaction by
| issuing the following command:
| /format IVTCM
|
| **************************************************
| * IMS INSTALLATION VERIFICATION PROCEDURE *
| **************************************************
|
|
| TRANSACTION TYPE : CONVERSATIONAL
| DATE : 04/19/00
|
| PROCESS CODE (*1) : DISPLAY
| (*1) PROCESS CODE
| LAST NAME : LAST1 ADD
| DELETE
| FIRST NAME : FIRST1 UPDATE
| DISPLAY
| EXTENSION NUMBER : 8-111-1111 TADD
| END
| INTERNAL ZIP CODE : D01/R01
|
|
| Person found! SEGMENT# :
||
| Figure 3. Example IMS Installation Verification Procedure Screen with Transaction Output
| Information
||
| WebSphere for z/OS Setup
| This section assumes you are familiar with WebSphere Application Server for z/OS
| and OS/390, its Administration application, and its Application Assembly tool.
| Related Reading:
| v For detailed information about how to use the Administration application, see
| WebSphere Application Server V4.0.1 for z/OS and OS/390 : System
| Management User Interface.
| v For detailed information about assembling and deploying an EJB onto a J2EE
| server, see WebSphere Application Server V4.0.1 for z/OS and OS/390 :
| Assembling Java 2 Platform, Enterprise Edition (J2EE) Applications.
| Configuring the WebSphere for z/OS J2EE Server for IMS Access
| To run an EJB on a WebSphere for z/OS J2EE server, you must configure
| WebSphere for z/OS to access IMS databases using ODBA. ODBA uses the
| database resource adapter (DRA) to access IMS databases. More details about the
| steps in this section are in IMS Version 7 Installation Volume 2: System Definition
| and Tailoring.
| Important: If you do not edit the jvm.properties file correctly, PSB allocation fails
| when using the IMS JDBC Resource Adapter.
| To configure the WebSphere for z/OS J2EE server to locate the IMS JBDC
| Resource Adapter:
| 1. Create a conversation and define the IMS JDBC Resource Adapter as a J2EE
| resource:
| a. Open the WebSphere Application Server for z/OS and OS/390
| Administration tool.
| b. Add a conversation.
| c. Navigate to the sysplex that will run the EJBs.
| d. Modify the sysplex properties by selecting Connection Management.
| e. Modify the J2EE properties by defining the CLASSPATH and LIBPATH
| environment variables:
| The expansion puts the following files (in UTF-8 format) in the same directory
| as the imsjava71.rar file:
| v IMSJdbcCustomService.xml
| v howto.html
| Related Reading: For more information about IMS JDBC Resource Adapter
| configuration, see the howto.html file. Because it is encoded in UTF-8 format,
| you can not read it in the OS/390 environment. To read the file, expand
| imsjava71.rar on your desktop.
| 3. Edit the jvm.properties file for WebSphere J2EE server regions that will access
| IMS databases to identify the location of the file IMSJdbcCustomService.xml.
| To edit the jvm.properties file, add the directory where the file
| IMSJdbcCustomService.xml is to the preconfigured custom services in the
| jvm.properties file.
| If you use the default IMS installation directory, enter:
| com.ibm.websphere.preconfiguredCustomServices=
| /usr/lpp/ims/imsjava71/IMSJdbcCustomService.xml
| Note: If you are setting up WebSphere for the first time and want to verify your
| installation, start the procedure in the following section “WebSphere for z/OS
| Installation Verification” on page 12.
| Note: These instructions use two conversations to deploy the IMS JDBC
| Resource Adapter and the Enterprise Archive (EAR). However, you can
| also deploy an EAR in the same conversation that deploys the IMS
| JDBC Resource Adapter instance.
| If you do set the subclass name, you must create a new instance of the IMS JDBC
| Resource Adapter for every database an EJB accesses. You can override the
| DLIDatabaseView subclass name (set in step 6) in the DataSource object by calling
| the setDatabaseView method and providing the fully-qualified name of the subclass.
| If you do not set the subclass name, you only need to deploy an instance of the
| IMS JDBC Resource Adapter for each DRA startup table. In the EJB, define the
| DLIDatabaseView subclass name (set in step 6) in the DataSource object by calling
| the setDatabaseView method and providing the fully-qualified name of the subclass.
| To deploy your application onto the WebSphere for z/OS J2EE server:
| 1. Package the EJB into an Enterprise Archive (EAR) using a development tool
| such as Websphere Studio Application Developer Integrated Edition.
| 2. Import the EAR into WebSphere for z/OS and OS/390 Application Assembly
| tool.
| 3. Create a resolved EAR suitable for deploying on a WebSphere for z/OS J2EE
| server.
| 4. Open the WebSphere Application Server for z/OS and OS/390 Administration
| application.
| 5. Add a conversation.
| 6. Navigate to the J2EEServers folder of the sysplex that will run the EJB.
| The following folders are displayed:
| J2EEServers
| Servers
| Systems
| J2EE Resources
| Logical Resource Mapping
| 7. Expand the J2EEServers folder and choose the server to install the EJB on.
| 8. Install the EJB.
| a. Specify the fully-qualified directory name of the EAR and the FTP server of
| the sysplex where the EJB will run.
| b. Set the JNDI name and path.
| Note: You can also use this procedure to install the dealership sample EAR, which
| is also in samples.tar. The sample file name is imsjavaDealership.ear and
| the DLIDatabaseView subclass name is
| samples.dealership.AUTPSB11DatabaseView.
| 1. Transfer the IVP EAR file in binary mode to your workstation:
| a. Expand the samples.tar file. For instructions, see the Readme file in the
| samples directory.
| b. Use FTP to transfer the file imsjavaIVP.ear to your workstation.
| 2. Deploy an instance of the IMS JDBC Resource Adapter:
| a. Open the WebSphere Application Server for z/OS and OS/390
| Administration tool.
| b. Add a conversation.
| c. Navigate to the sysplex that will run the EJBs.
| The following folders are displayed:
| J2EEServers
| Servers
| Systems
| J2EE Resources
| Logical Resource Mapping
| d. Add a J2EE resource. The resource name is your choice. The type is
| IMSJdbcDataSource.
| e. Add a J2EE resource instance with the following information:
| v J2EE Resource Instance Name: your choice, such as
| IMSJavaIVPDataSource
| v System Name: name of system that will run the server
| v DLIDatabaseView subclass name: samples.ivp.DFSIVP37DatabaseView
| v DRA Startup Table: name of your DRA table
| f. Save and activate the conversation.
| 3. Assemble the IVP EAR:
| a. Import the EAR into WebSphere for z/OS and OS/390 Application Assembly
| tool.
| b. Create a resolved EAR suitable for deploying on a WebSphere for z/OS
| J2EE server.
| 4. Deploy the IVP EAR, which contains the IVP JAR file and the IVP Web Archive
| (WAR):
| a. Open the WebSphere Application Server for z/OS and OS/390
| Administration application.
| b. Add a conversation.
| CICS Restrictions
| In a CICS environment, only one PSB can be allocated at a time. Therefore, an
| application can only have one active JDBC connection at a time. The application
| must close the JDBC connection before opening another JDBC connection.
| “General Restrictions” on page 3 lists other restrictions.
| CICS Configuration
| To configure CICS for IMS Java, modify the CICS JVM profile DFHJVMPR. The
| default PDS is DFHJVM.
| For example, if you use the default installation directory, add the following line:
| TMSUFFIX=/usr/lpp/ims/imsjava71/imsjava.jar
| 2. Update the LIBPATH variable to contain the location of the IMS Java file
| libJavTDLI.so.
| For example, if you use the default installation directory, add the following line:
| LIBPATH=/usr/lpp/ims/imsjava71
| 3. Change the HFS dfjjvmpr.props file to set the shareable application classpath
| (The location of this file is specified via the JVMPROPS variable in the CICS
| JVM profile). Point this classpath to the locations of the user applications. For
| example:
| ibm.jvm.shareable.application.class.path=/imsjava/myApplication
| Related Reading: For detailed information on CICS system definition, see CICS
| Transaction Server for OS/390: CICS System Definition Guide.
| Installation Verification
| After you configure CICS to run IMS Java applications, verify that IMS Java is
| installed correctly and that CICS is configured correctly to run IMS Java
| applications.
| If the transaction ran successfully, the program correctly returns a first name,
| last name, zip code, and extension.
|
| DB2 Setup
| DB2 Restrictions
| In a WLM-managed stored procedure address space configured to run LANGUAGE
| JAVA stored procedures, a considerable amount of storage is used for the Java
| Virtual Machine. The NUMTCB parameter must be adjusted accordingly. The
| recommended NUMTCB is a maximum of 7.
| DB2 Configuration
| The stored procedures must be compiled (javac) by JDK 1.3.1.
| For example:
| ENVAR("CLASSPATH=/imsjava",
| "DB2_HOME=/usr/lpp/db2/dev710",
| "JAVA_HOME=/usr/lpp/java/J1.3",
| "LIBPATH=/usr/lpp/ims/imsjava71",
| "TMSUFFIX=/usr/lpp/ims/imsjava71/imsjava.jar)
| These classes can be found in the samples.tar file (by default in the
| /usr/lpp/ims/imsjava71/samples directory).
| To verify that DB2 is configured correctly and that IMS Java is installed correctly:
| 1. Set CLASSPATH in JAVAENV data set to samples.jar (default is
| /usr/lpp/ims/imsjava71/samples.jar)
| 2. Submit the following JCL to define the stored procedure to DB2:
| If the program ran sucessfully, it will display a first name, last name, extension,
| and zip code.
|
| DLIModel Utility Setup
| Before the DLIModel utility can be run, from the MVS USS prompt or by running
| JCL, some preparation is required. Since DLIModel is a Java application, this
| preparation depends on the Java environment in your installation. Guidelines are
| provided here, but they may require modification in order to fit your environment.
| If you do not want to change the CLASSPATH environment variable, you can
| use the -cp option of the java command in step 5
| 2. Copy the member DFSMODEL from its distribution library SDFSISRC to the
| PROCLIB from where your installation submits IMS procedures for batch
| execution.
| 3. Rename the procedure, if desired. This book assumes that you have renamed it
| DLIMODEL.
| 4. Determine if you need to create a script file.
| The script file is an HFS file with a single-line Java command that runs the
| DLIModel utility (a Java application). The file is referenced in the PARM field in
| the EXEC statement. You need a script file if the command—including the path
| and file name of the control data set—exceeds the 100-byte limit. You do not
| need a script file if you do not exceed the limit and if you tailor the procedure by
| placing the java command directly in the PARM field.
| 5. If needed, create an HFS script file with the java command. (If you do not need
| the script file, use the same syntax as follows for the command in the PARM
| field.)
| In the HFS script file, write a single-line command using the following syntax:
| (1) (2)
QQ java com.ibm.ims.metagen.DLIModel “$1” PDS QT
|
| Notes:
| 1 The simple form assumes that the java command is accessible through
| your PATH envirnoment variable and that the CLASSPATH
| environment variable includes all necessary .jar files.
| 2 The $ symbol can vary by locale, so you use the valid value for your USS
| setup.
| com.ibm.ims.metagen.DLIModel
| Main class of this DLIModel utility.
| ″$1″
| Symbolic parameter that takes the value of the data set name of the utility
| control statement data set. This symbolic parameter is set from the
| DSNAME parameter in the EXEC statement that runs the DLIMODEL
| procedure.
| PDS
| Required parameter is a string literal.
| If your environment variables are not set as described previously (for example,
| you are running the utility on an experimental or trial basis), you can use the
| following syntax for the command (the single line command has been wrapped
| to fit the page):
| Related Reading: For more information about the MVS BPXBATCH utility, see
| OS/390: Unix Systems Services User’s Guide and OS/390: Unix Systems
| Services Command Reference.
| 6. If you used a script file, reference the file in the PARM field of the EXEC
| statement in the DLIMODEL procedure.
| As provided, the PARM field references /usr/lpp/ims/imsjava71/dlimodel/go.
| Alternately, you can add a path prefix to the java command and use the -cp option
| of the java command, as described in step 5 on page 20 in the previous section.
| Note: Both styles require that you first describe your IMS databases to the IMS
| Java classes through a metadata class, as described below under
| “Describing Your IMS Databases to IMS Java” on page 24.
| This chapter uses the sample applications shipped with IMS Java to show how to
| access IMS database. For information on expanding and locating these files, see
| the Readme file in the samples directory.
| All samples use a car dealership example and use JDBC for database processing.
| All samples process a common set of databases, and the jobs to define and load
| these databases are contained in the directory samples/dealership/databases. For
| information on how to run the database definition and load jobs, see the IMS
| sample Readme file in the directory samples/dealership/ims/Readme.
| Related Reading: For a full specification of the classes used in this chapter, see
| the JavaDoc shipped with IMS Java. If using the default installation directory, the
| JavaDoc is in directory usr/lpp/ims/imsjava71/docs/.
|
| Introduction to the Example Environment
| In this chapter and in Chapter 4, “Writing a Java Application Program” on page 45, a
| sample application program is introduced. The sample program uses an automobile
| dealership program for illustration purposes. This and other automobile dealership
| applications are available in the samples.tar file shipped with the IMS Java product
| (See the Readme file in the samples directory for instructions on how to expand
| and access these sample applications).
| The sample database contains five segment types. The root segment is the Dealer
| segment. Its child segment is the Model segment. Under the Model segment are its
| children: the segments Order, Stock, and Sales. This is the same database
| example that will be used in Chapter 3, “Accessing an IMS Database”, and in
| “Example 4. Example with Multiple Control Statements” on page 85. See Figure 6
| on page 25 for the DBD of this database.
|
|
| Figure 4. Example Database Hierarchy
|
| The Dealer segment identifies a dealer selling cars. The segment contains a unique
| dealer number, dealer name and address, and annual sales information.
| Dealers carry car types, each of which has a corresponding Model segment. A
| Model segment contains a unique type code, descriptive information about the car,
| and its price.
| There is an Order segment for each car ordered for the dealership. The segment is
| sequenced by an order number that contains information about the options, pricing,
| order date, and the customer who ordered the car. When a car is delivered to fill a
| particular order, its serial number and delivery date are added to the segment. The
| segment is deleted when the customer (or dealer) accepts the car.
| A Stock segment is created for each car that is available for sale in the dealer’s
| inventory. The segment is sequenced by a serial number that is unique to a given
| model. It contains descriptive information about the car and the date it was
| delivered to the dealer. The segment remains in the database until the car is sold
| from stock.
| Finally, when the car is sold, a Sales segment is created. This segment is
| sequenced by sale date and contains information about the car sold and the
| purchaser.
|
| JDBC Access Method
| There are two ways you can prepare the metadata class for a PSB:
| v Provide the application PSB source and any related DBD source to the DLIModel
| utility, and specify the generation of the IMS Java metadata class. This is the
| recommended technique and is described in Chapter 5, “DLIModel Utility” on
| page 61.
| This chapter assumes that you have prepared a metadata class by using the
| DLIModel utility.
| The examples used for the rest of this chapter are based on the following simple
| application. The PSB for the application is as shown in Figure 5. This database is
| the Automobile Dealership database that was introduced in “Introduction to the
| Example Environment” on page 23.
|
| DLR_PCB1 PCB TYPE=DB,DBDNAME=DEALERDB,PROCOPT=GO,KEYLEN=42
| SENSEG NAME=DEALER,PARENT=0
| SENSEG NAME=MODEL,PARENT=DEALER
| SENSEG NAME=ORDER,PARENT=MODEL
| SENSEG NAME=SALES,PARENT=MODEL
| SENSEG NAME=STOCK,PARENT=MODEL
| PSBGEN PSBNAME=DLR_PSB,MAXQ=200
| END
|
| Figure 5. Example PSB Definition
|
| The physical DBD referenced by this PSB is shown in Figure 6.
|
| DBD NAME=DEALERDB,ACCESS=(HDAM,OSAM),RMNAME=(DFSHDC40.1.10)
| SEGM NAME=DEALER,PARENT=0,BYTES=94,
| FIELD NAME=(DLRNO,SEQ,U),BYTES=4,START=1,TYPE=C
| FIELD NAME=DLRNAME,BYTES=30,START=5,TYPE=C
| SEGM NAME=MODEL,PARENT=DEALER,BYTES=43
| FIELD NAME=(MODTYPE,SEQ,U),BYTES=2,START=1,TYPE=C
| FIELD NAME=MAKE,BYTES=10,START=3,TYPE=C
| FIELD NAME=MODEL,BYTES=10,START=13,TYPE=C
| FIELD NAME=YEAR,BYTES=4,START=23,TYPE=C
| FIELD NAME=MSRP,BYTES=5,START=27,TYPE=P
| SEGM NAME=ORDER,PARENT=MODEL,BYTES=127
| FIELD NAME=(ORDNBR,SEQ,U),BYTES=6,START=1,TYPE=C
| FIELD NAME=LASTNME,BYTES=25,START=50,TYPE=C
| FIELD NAME=FIRSTNME,BYTES=25,START=75,TYPE=C
| SEGM NAME=SALES,PARENT=MODEL,BYTES=113
| FIELD NAME=(SALDATE,SEQ,U),BYTES=8,START=1,TYPE=C
| FIELD NAME=LASTNME,BYTES=25,START=9,TYPE=C
| FIELD NAME=FIRSTNME,BYTES=25,START=34,TYPE=C
| FIELD NAME=STKVIN,BYTES=20,START=94,TYPE=C
| SEGM NAME=STOCK,PARENT=MODEL,BYTES=62
| FIELD NAME=(STKVIN,SEQ,U),BYTES=20,START=1,TYPE=C
| FIELD NAME=COLOR,BYTES=10,START=37,TYPE=C
| FIELD NAME=PRICE,BYTES=5,START=47,TYPE=C
| FIELD NAME=LOT,BYTES=10,START=52,TYPE=C
| DBDGEN
| FINISH
| END
|
| Figure 6. DBD Sample Definition
|
| The DLIModel utility produces a DLIModel Java Report of its generated metadata
| structure. For an example of the report produced by DLIModel see Figure 7 on
| page 26.
|
|
| Figure 7. The IMS Java Summary Report
|
| The DLIModel Summary Report provides you with the following information:
| v The name of the metadata class (DealerDatabaseView), to use when you
| establish a connection to the database.
| v The hierarchy of segments in each PCB view.
| v The fields within each segment. These will include the fields specified in the
| DBD, but also include additional fields specified to DLIModel based (for example)
| on field layouts of segments in existing applications. For example, the fields
| DealerAddress and YTDSales in the Dealer segment are added fields.
| v The names of PCBs, segments, and fields to use in your JDBC calls. These
| names may be alias names assigned to the IMS entities. Alias names are
| intended to be more representative and intuitive identifiers for your Java
| Related Reading: For details of the DLIModel Java Report and its contents, see
| “DLIModel Java Report” on page 64.
|
| Figure 8. IMS DB Segments and Fields with Their Corresponding DB2 Tables and Columns
|
| For the purpose of writing JDBC calls, a database segment definition defines the
| fields for a set of segment instances similar to the way a relational table defines
| columns for a set of rows in a table. In this way, segments relate to tables, and
| fields in a segment relate to columns in a table. And so, the name of an IMS
| segment from the summary report becomes the table name in an SQL query, and
| the name of a field becomes the column name in the query.
| For example, in the query below, Model is a segment name that is used as a table
| name in the query:
| SELECT * FROM Model
| In both of the preceding examples, Model and ModelTypeCode are alias names
| assigned by using the DLIModel utility. These names will likely not be the same
| eight character names used in the database definition for IMS. Alias names are
| described in further detail in Chapter 5, “DLIModel Utility” on page 61 and aliases
| simply act as references to the eight character names described in the IMS DBD
| (database definition).
|
| Figure 9. PCB-Qualifying SQL Query Example
| Use the following import statement to make JDBC classes available by their
| unqualified class names:
| import java.sql.*;
| When the following line from Figure 10 on page 30 is executed, DLIDriver, a class in
| com.ibm.ims.db, registers itself with the JDBC DriverManager:
| Class.forName("com.ibm.ims.db.DLIDriver");
| When the following line from Figure 10 on page 30 is executed, the JDBC
| DriverManager determines which of the registered drivers supports the supplied
| string.
| connection = DriverManager.getConnection
| ("jdbc:dli:dealership.application.DealerDatabaseView");
| In this case, because the supplied string begins with jdbc:dli:, JDBC DriverManager
| locates the DLIDriver instance and requests that it create a connection.
|
|
| Figure 10. JDBC Application
|
| The following list describes the JDBC 2.1 required interfaces that are implemented
| in the database package, including limitations in the DL/I implementation of these
| interfaces.
| java.sql.Connection
| java.sql.Connection is an object that represents the connection to the
|
| Figure 11. Establish a Database Connection
|
| java.sql.DatabaseMetaData
| DatabaseMetaData defines a set of methods to query information about the
| database, including capabilities the database might or might not support.
| The class is provided for tool developers and is normally not used in client
| programs. Much of the functionality is specific to relational databases and is
| not implemented for DL/I databases.
| java.sql.Driver
| The Driver interface itself is not usually used in client programs, although
| an application needs to dynamically load a particular Driver implementation
| by name. One of the first lines in an IMS JDBC program for DL/I access
| must be:
| Class.forName("com.ibm.ims.db.DLIDriver");
| This code loads the Driver and causes the Driver implementation to register
| itself with the DriverManager so that the driver can later be found by
| DriverManager.getConnection. The Driver implementation creates and
| returns a Connection object to the DriverManager. The DL/I implementation
| of JDBC is not fully JDBC compliant and the Driver member jdbcCompliant
| returns false.
| java.sql.Statement
| A Statement interface is returned from Connection.createStatement. The
| Statement and its subclass PreparedStatement define the interfaces that
| accept SQL statements and return tables as ResultSet objects. The code to
| create a statement is as follows:
| Statement statement = connection.createStatement();
| Rather than building a complete set of results after a query is run, the DL/I
| implementation of ResultSet retrieves a new segment occurrence each time
| ResultSet.next is called.
| The following table shows the available get methods for accessing data of a certain
| JDBC type.
| The methods that are marked with “X” are methods designed for accessing the
| given data type. No truncation or data loss occurs using those methods. The
| methods that are marked with “O” are all other legal calls; however, data integrity
| cannot be ensured using those methods. If the box is empty (it contains neither an
| “X” nor an “O”), using that method for that data type will result in an exception.
| Table 2. ResultSet.getxxx Methods to Retrieve JDBC Types
| JDBC Types
PACKEDDECIMAL
ZONEDECIMAL
TIMESTAMP
SMALLINT
VARCHAR
INTEGER
DOUBLE
TINYINT
BINARY
BIGINT
FLOAT
CHAR
DATE
TIME
| ResultSet.getxxx
BIT
| Methods
| getByte X O O O O O O O O O O
| getShort O X O O O O O O O O O
| getInt O O X O O O O O O O O
| getLong O O O X O O O O O O O
| getFloat O O O O X O O O O O O
| getDouble O O O O O X O O O O O
| getBoolean O O O O O O X O O O O
| getString O O O O O O O X X O O O O O O
| getBigDecimal O O O O O O O O O X X
| getBytes X
| getDate O O X O
| getTime O O X O
| getTimestamp O O O O X
|
| Note: PACKEDDECIMAL and ZONEDDECIMAL are IMS Java JDBC types. All
| others are standard SQL types defined in SQL92.
| Restriction: PackedDecimal and ZoneDecimal data types do not support the Sign
| Leading or Sign Separate modes. Sign information is always stored with the Sign
| Trailing method.
| General Mappings from COBOL Copybook Types to IMS Java and Java
| Data Types
| Table 3 on page 34 describes how COBOL copybook types are mapped to
| DLITypeInfo constants and Java data types.
| SELECT
| A SELECT statement is a query used as a top-level SQL statement. A SELECT
| statement can be executed against a Statement or PreparedStatement object that
| returns the results as a ResultSet object. Figure 12 on page 36 shows sample code
| that uses the results of a SELECT query to update modelOutput with the model
| information. This example requires an inputMessage with the ModelTypeCode.
| Notice that the PCB reference name, DealershipDB, qualifies the Model segment
| name in the query string.
| Segment-Qualifying Fields
| SQL dictates that whenever a field is common between two tables in an SQL query,
| the desired field must be table qualified to resolve the ambiguity. Similarly,
| whenever a field name is common in any two segments along a hierarchical path,
| the field must be segment qualified. For example, if a PCB has two segments,
| segment ROOT and segment CHILD, and both possess a field named id, any query
| referencing the id field must be segment qualified. The following example is
| incorrect because the id field is not segment qualified:
| SELECT id
| FROM PCBName.CHILD
| WHERE id=’10’
| Recommendations:
| v For performance reasons, always segment qualify fields (unless readability is
| seriously sacrificed). A performance improvement is realized since IMS Java
| does not need to search through all the segments to locate the field and check
| for ambiguity.
| v It is not necessary to provide the PCB reference name on the query unless the
| query is ambiguous without it; however, it is recommended that you always
| provide it to remove ambiguity and to remove the need for checking.
|
| Figure 12. Example of SELECT Query Results
|
| Note: Note the use of trim() in Figure 12. The method trim() is used because
| IMS character fields are padded with blanks if they are not long enough. It
| trims off the extra blanks in the return.
| Figure 12 illustrates the use of a Statement object for executing an SQL query. You
| can also use a PreparedStatement object to execute an SQL query. A
| PreparedStatement object has two advantages over a Statement object:
| v The SQL can be parsed one time for many executions of the query
| v You can build the query and use substitute values with each execution
| FROM
| A FROM clause in IMS Java differs from standard SQL in that no explicit joins are
| required nor allowed. Rather, the deepest segment to be accessed should be listed
| in the FROM clause. This then implies a join of all the segments starting with the
| one listed in the FROM clause up the hierarchy to the root. For more information
| see “JDBC Access Method” on page 24.
| WHERE
| By using IMS Java to write IMS applications, you can avoid the long process of
| coding segment search arguments (SSAs) for every segment in the path leading to
| the segment being queried. Instead, you can use the IMS Java API for SQL queries
| to retrieve results from any segment in the path leading to the segment being
| queried.
| The primary difference between SQL queries to relational databases and JDBC
| queries to IMS using IMS Java is that the hierarchical structure of an IMS database
| eliminates the need for the join required for tables in relational databases.
|
| Figure 13. Sample Query
| You must query two independent tables (Dealer and Model) and indicate how they
| are joined in the WHERE clause.
| In an IMS Java application, you can write the query in Figure 14 to access the
| same data in a hierarchical database in a WHERE clause:
|
| SELECT Dealer.Address
| FROM DealershipDB.Model
| WHERE Model.CarMake = ’AnyCarModel’
|
| Figure 14. Sample Query
| In a hierarchical database, all data in segments along the hierarchical path to the
| target segment are implicitly included in the query results and therefore do not need
| to be explicitly stated. In Figure 14, the information about the Dealer segment is
| included in the result set, because it is along the hierarchical path to the Model
| segment.
| If fields from more than one segment are desired, they must all be explicitly
| requested in the SELECT clause.
| You can use the following operators between field names and values in individual
| predicates:
| <
| <=
| =
| =<
| <
| !=
| You can combine multiple predicates with AND and OR operators. However, you
| cannot use parentheses and AND always takes precedence over OR.
| INSERT
| An INSERT statement inserts a segment instance with the specified data under any
| number of parent segments matching the criteria specified in the WHERE clause.
| All column names must be in the statement, except when the value of a field is
| specifically set in the database view. For more information see “Adding Default
| Values for Fields of a Segment” on page 99. Figure 15 shows an example of an
| INSERT statement that inserts a field in the database:
|
| String insertString = "INSERT INTO DealershipDB.Sales "
| + "(DateSold, PurchaserLastName, PurchaserFirstName, "
| + "PurchaserAddress, SoldBy, StockVINumber)"
| + " VALUES (’07032000’, ’Beier’, ’Otto’, "
| + "’101 W. 1st Street, Springfield, OH’, "
| + "’S123’, ’1ABCD23E4F5678901234’) "
| + "WHERE Dealer.DealerNumber = ’A123’"
| + "’ AND ModelTypeCode = ’K1’)";
|
| Figure 15. Sample INSERT Statement
|
| It is possible to set default values for any field in a segment. For more information
| see “Adding Default Values for Fields of a Segment” on page 99.
| DELETE
| A DELETE statement can delete any number of segment occurrences matching the
| criteria specified in the WHERE clause. A DELETE statement with a WHERE clause
| also deletes the child segments of the matching segments. If no WHERE clause is
| specified, all of the segment occurrences of that type are deleted as are all of its
| child segment occurrences. Figure 16 shows an example of a DELETE statement:
|
| String updateString = "DELETE from DealershipDB.Order WHERE "
| + "Dealer.DealerNumber = ’"
| + dealerDesired+ "’ AND "
| + "OrderNumber = ’" + orderDesired + "’";
| try {
| Statement statement = connection.createStatement();
| int results = statement.executeUpdate(updateString);
| ...
| }
| catch (SQLException e) {
| ...
| }
|
| Figure 16. Sample DELETE Statement
|
| UPDATE
| An UPDATE statement modifies the value of any number of segment occurrences.
| A SET clause contains at least one assignment. In each assignment, the values to
| the right of the equal sign are computed and assigned to columns to the left of the
| equal sign. For example, the UPDATE statement in Figure 17 is called to accept an
| order. When a customer accepts an order, the car’s “SerialNo” and delivery dates
| are filled in:
|
| String updateString = "UPDATE DealershipDB.Order "
| + "SET SerialNo = ’"
| + inputMessage.getString("StockVINumber").trim()
| + "’, "
| + "DeliverDate = ’"
| + inputMessage.getString("Date").trim()
| + "’ WHERE OrderNumber = ’"
| + inputMessage.getString("OrderNumber").trim()
| + "’";
|
| Figure 17. Sample UPDATE Statement
|
| The PreparedStatement performs the following only once before repeated database
| calls are made:
| 1. Parses the SQL
| 2. Cross-references the SQL with the IMS Java DLIDatabaseView
| 3. Builds SQL into SSAs before a database call is made
| Note: When considering the effects of the database hierarchy on your JDBC
| operations, you can find a description of the hierarchy, as it appears in your
| application view, in the DLIModel Java Report.
| You may create the required classes by coding them manually (see Appendix A,
| “Manually Creating IMS Java Metadata Classes” on page 99), or by running the
| DLIModel utility (See Chapter 5, “DLIModel Utility” on page 61). It is recommended
| that you use the DLIModel utility wherever possible.
|
| DealerDatabaseView dealerView = new DealerDatabaseView();
| DLIConnection connection = DLIConnection.createInstance(dealerView);
|
| Figure 18. Creating a DLIConnection Object
|
| Building SSAs
| SSAs are used to identify the segment to which a DL/I call applies. Due to the
| hierarchical structure DL/I uses, you often have to specify several levels of SSAs to
| access a segment at a low level in the hierarchy. An SSAList is a collection of one
| or more SSAs and the SSAList is what is used in making any DL/I call. The
| SSAList is also where you specify which database you want to access within a
| DLIDatabaseView by providing the PCB reference name.
| Figure 19 on page 43 illustrates how to create an SSAList that will find all “Alpha”
| cars made in 1989:
|
| Figure 19. Creating an SSAList
|
| Accessing DL/I Data using SSAs
| You can now issue a database call by invoking the desired access method on
| DLIConnection passing in:
| v the SSAList
| v an instance of the segment, that will be the intended target of the database call
| results
| This passed-in instance should be obtained by calling the cloneSegment method on
| the DLIDatabaseView. Finally, the passed-in segment can be examined for the
| results of the query.
| The following example demonstrates calling and printing-out the results using the
| SSAList built in the preceding section:
| DLISegment model = dealerView.cloneSegment("Model");
| boolean recordRead = connection.getUniqueSegment(model, modelSSAList);
| while (recordRead) {
| System.out.println("Car Name: " + model.getString("ModelName"));
| recordRead = connection.getNextSegment(model, modelSSAList);
| }
| All samples use a car dealership example and use JDBC for database processing.
| All samples process a common set of databases, and the jobs to define and load
| these databases are contained in the directory samples/dealership/databases. For
| information on how to run the database definition and load jobs, see the IMS
| sample Readme file in the directory samples/dealership/ims/Readme.
In this Chapter:
v “IMS Applications”
v “CICS Applications” on page 59
v “DB2 Stored Procedures” on page 59
IMS Applications
| IMS Java applications can run in a DB/DC and DBCTL environments. IMS Java
| does not support batch processing.
Message Queuing
After you provide input in one of the forms described above, the message is either
queued or sent directly to command process or modules.
Specifically, all full-function database input and output messages are placed in
message queues, waiting to be enqueued to their destinations or points of
completion. However, before getting to the points of completion, IMS message
queues are held in buffers in main storage until they are either directed to their
destination or there is a backlog of messages arriving in the queue. If there are
more messages entering the queue than exiting, IMS writes messages to the
message queue data sets until they are directed to their final destinations.
Related Reading: See the IMS Primer for general information on IMS message
queues.
| Related Reading: For a full specification of the classes used in this chapter, see
| the JavaDoc shipped with IMS Java. If using the default installation directory, the
| JavaDoc is in directory usr/lpp/ims/imsjava71/docs/.
| This example code subclasses IMSFieldMessage to make the fields in the message
| available to the program and creates an array of DLITypeInfo objects for the fields
| in the message. For the DLITypeInfo, the code identifies first the field name, then
| the data type, the position, and finally the length of the individual fields within the
| array. This allows the application to use the access functions within
| IMSFieldMessage to automatically convert the data from its format in the message
| to a Java type that the application can process. In addition to the message-specific
| fields it defines, IMSFieldMessage provides access functions that allow it to
| determine the transaction code and the length of the message.
| package dealership.application;
| import com.ibm.ims.db.*;
| import com.ibm.ims.base.*;
| import com.ibm.ims.application.*;
|
| /* Subclasses IMSFieldMessage to define application’s input messages */
| public class InputMessage extends IMSFieldMessage {
|
| /* Creates array of DLITypeInfo objects for the fields in message */
| final static DLITypeInfo[]fieldInfo={
| new DLITypeInfo("ModelTypeCode", DLITypeInfo.CHAR, 1, 2)
| };
|
| public InputMessage() {
| super(fieldInfo, 2, false);
| }
| }
| This example code creates an array of DLITypeInfo objects and then passes that
| array, the byte array length, and the boolean value false (indicates a non-SPA
| message) to the IMSFieldMessage constructor. For each DLITypeInfo object, you
| must first identify the field data type, then the field name, the field offset in the byte
| array, and finally the length of the byte array.
|
Figure 21. Subclass IMSFieldMessage: Output Message Sample Code
| JMP programs are started when IMS receives a message with a transaction code
| for the JMP program and schedules the message. JMP programs end when there
| are no more messages with that transaction code to process.
| JMP Program Without Rollback: Every time the program runs, the program
| connects to an IMS database and disconnects when it has processed all of the
| messages. A transaction begins when the program gets an input message and ends
| when the program commits the transaction. Database processing is done only after
| the getUniqueMessage call and before the commit call. The program cannot
| perform database processing after the commit call and either before the next
| getUniqueMessage call or the return.
| public void doBegin() ... { //Application logic runs
|
| conn = DriverManager.getConnection(...); //Establish DB connection
|
| repeat {
|
| MessageQueue.getUniqueMessage(...); //Get input message, which
|
| results=statement.executeQuery(...); //Perform DB processing
| ...
| MessageQueue.insertMessage(...); //Send output messages
| ...
| IMSTransaction.commit(); //Commit and end transaction
| }
|
| conn.close(); //Close DB connection
| return;
| }
| JMP Program using Rollback: A JMP program can roll back database
| processing and output messages any number of times during a transaction. A
| rollback call backs out all database processing and output messages to the most
| recent commit. The transaction must still end with a commit call when the program
| issues a rollback call, even if there is no further database processing or messages
| after the rollback.
| public void doBegin() ... { //Application logic runs
|
| conn = DriverManager.getConnection(...); //Establish DB connection
|
| repeat {
|
| MessageQueue.getUniqueMessage(...); //Get input message, which
|
| results=statement.executeQuery(...); //Perform DB processing
| ...
| MessageQueue.insertMessage(...); //Send output messages
| ...
| IMSTransaction.rollback(); //Back out of DB processing and
| //output messages
|
| results=statement.executeQuery(...); //Perform more DB processing
| //(optional)
| ...
| MessageQueue.insertMessage(...); //Send more output messages
| //(optional)
| ...
| IMSTransaction.commit(); //Commit and end transaction
| JBP Program using Rollback: Like JMP programs, JBP programs can also back
| out of database processing and output messages. A final commit call is required
| before the program can end, even if no database processing occurs or output
| messages are sent after the last rollback call.
| public void doBegin() ... { //Application logic runs
|
| conn = DriverManager.getConnection(...); //Establish DB connection
|
| repeat {
|
| repeat {
|
| results=statement.executeQuery(...); //Perform DB processing
| ...
| MessageQueue.insertMessage(...); //Send output messages
| ...
| IMSTransaction.rollback(); //Back out of DB
| //messages
|
| results=statement.executeQuery(...); //Perform more DB
| //processing (optional)
| ...
| MessageQueue.insertMessage(...); //Send more output
| //messages (optional)
| ...
| }
|
| IMSTransaction.commit(); //Periodic commits divide work
| }
|
| conn.close(); //Close DB connection
| return;
| }
Conversational Transactions
| A conversational program runs in a JMP region and processes conversational
| transactions that are made up of several steps. It does not process the entire
| transaction at the same time. A conversational program divides processing into a
| connected series of terminal-to-program-to-terminal interactions. Use conversational
| processing when one transaction contains several parts.
| Defining a SPA Message: Here are the steps to define a SPA message in a
| conversational program:
| 1. Define the SPA message (including the boolean as a SPA parameter). By
| default, all messages going to (input) and from (output) an IMS Java application
| are transmitted as EBCDIC character data. To use a different type of encoding,
| you must call the IMSFieldMessage inherited member setDefaultEncoding and
| provide the new encoding. This encoding can be any Java supported encoding.
| In Figure 23, the default encoding is specified as UTF-8.
|
public class SPAMessage extends IMSFieldMessage {
static DLITypeInfo[] fieldInfo = {
new DLITypeInfo("SessionNumber",DLITypeInfo.SMALLINT,1, 2),
new DLITypeInfo("ProcessCode", DLITypeInfo.CHAR, 3, 8),
new DLITypeInfo("LastName", DLITypeInfo.CHAR, 11,10),
new DLITypeInfo("FirstName", DLITypeInfo.CHAR, 21,10),
new DLITypeInfo("Extension", DLITypeInfo.CHAR, 31,10),
new DLITypeInfo("ZipCode", DLITypeInfo.CHAR, 41, 7),
new DLITypeInfo("Reserved", DLITypeInfo.CHAR, 48,19) };
| public SPAMessage() {
| super(fieldInfo, 66, true);
| setDefaultEncoding("UTF-8");
| }
| }
|
| Figure 23. Defining a SPA Message
|
2. Read the SPA message before reading the application messages:
| try {
| // Get the SPA data
| msgReceived = msgQ.getUniqueMessage(spaMessage);
| }
| catch (IMSException e)
| {
| if (e.getStatusCode() !=
| JavaToDLI.MESSAGE_QUEUED_PRIOR_TO_LAST_START)
| throw e;
| }
| if (!msgReceived)
| outputMessage.setString("Message","UNABLE TO READ SPA");
| else if (!msgQ.getNextMessage(inputMessage))
| // No input message received
| outputMessage.setString("Message","NO INPUT MESSAGE");
| else if ((spaMessage.getShort("SessionNumber")==0)
| && (!inputMessage.getString("ProcessCode").trim().equals("END"))
| && (inputMessage.getString("LastName").trim().equals("")))
| // New Conversation. User has to specify last name.
| outputMessage.setString("Message","LAST NAME WAS NOT SPECIFIED");
| else {
| }
|
| Figure 24. Reading the SPA Message
|
| The following code defines two input messages that comprise a multi-segment
| message:
| public class InputMessage1 extends IMSFieldMessage {
|
| final static DLITypeInfo[] segmentInfo = {
| new DLITypeInfo("Field1", DLITypeInfo.CHAR, 1, 10),
| new DLITypeInfo("Field2", DLITypeInfo.INTEGER, 11, 4)
| };
|
| public InputMessage1() {
| super(segmentInfo, 14, false);
| }
| }
|
| public class InputMessage2 extends IMSFieldMessage {
|
| final static DLITypeInfo[] segmentInfo = {
| new DLITypeInfo("Field1", DLITypeInfo.CHAR, 1, 10),
| new DLITypeInfo("Field2", DLITypeInfo.CHAR, 11, 8)
| };
|
| public InputMessage2() {
| super(segmentInfo, 18, false);
| }
| }
| The following code illustrates how the message queue is used to retrieve both
| messages:
| //Create a message queue
| IMSMessageQueue messageQueue = new IMSMessageQueue();
| //Create the first input message
| InputMessage1 input1 = new InputMessage1();
| //Create the second input message
| InputMessage2 input2 = new InputMessage2();
|
| try {
| //Read the first message from the queue
| messageQueue.getUniqueMessage(input1);
| ...
| //Read the second message from the queue
| messageQueue.getNextMessage(input2);
| ...
| } catch (IMSException e) {
| ...
| }
|
| Figure 26. Example Output Message
Note: The creation of the DLITypeInfoList object has no provision for specifying its
type. DLITypeInfoList hard codes the type of the fields to
DLITypeInfo.TYPELIST. This design is not constrained to any specific level of
nesting. Within the declaration of model TypeInfo in Figure 26, any of the
array members could be instances of DLITypeInfoList.
The following code uses field indexes instead of field names to make the same
change to the ModelOutput message:
ModelOutput output= new ModelOutput();
output.setString("2.4.3", "Red");
| Because DLISegment objects are defined using DLITypeInfo objects exactly like
| IMSFieldMessages, you can also use these repeating structures within your
| definitions of DLISegment subclasses. If you do this, however, and you wish to use
| DLIModel, you will have to modify the generated classes from the utility. DLIModel
| will not use DLITypeInfoList definitions in its generated classes. However, you
| cannot access fields defined in this manner using an SQL query.
2. Define separate input messages for each request. Each of these input
messages contains the same “CommandCode” field as its first field. Each of
these input messages also uses an IMSFieldMessage constructor that takes an
IMSFieldMessage and a DLITypeInfo array. This constructor allows you to
remap the contents of the primary input message using the same type of
information with each request; therefore, you do not copy the I/O area of the
message, only a reference to this area. Figure 28 on page 58 illustrates code
that created the input messages for the requests “ShowModelDetails,”
“FindACar,” and “CancelOrder.”
while (getUniqueMessage(inputMessage)) {
string commandCode=inputMsg.getString("CommandCode").trim();
if (commandCode.equals("ShowModelDetails")) {
showModelDetails(new ShowModelDetailsInput(inputMessage));
} else if(commandCode.equals("FindACar")) {
findACar(new FindACarInput(inputMessage));
} else {
//process an error
}
CICS Applications
The following programming model outlines the supported structure for CICS
applications that use IMS Java. The models are not complete, but show the normal
flow of the application for both the JDBC and SSA access methods. This model use
JDBC, but for the IMS Java hierarchic database interface method, database access
happens in the same places in the program flow as with JDBC.
public static void main(CommAreaHolder cah) { //Receives control
repeat {
results = statement.executeQuery(...); //Perform DB processing
...
//send output to terminal
}
repeat {
results = statement.executeQuery(...); //Perform DB processing
...
}
| In This Chapter:
| v “DLIModel Utility Overview”
| v “Requirements and Restrictions of the DLIModel Utility” on page 63
| v “Output Types of the DLIModel Utility” on page 64
| v “Control Statements for the DLIModel Utility” on page 66
| v “Running the DLIModel Utility” on page 74
| v “Examples of Using the DLIModel Utility” on page 77
|
| DLIModel Utility Overview
| Processing IMS databases with an IMS Java application requires that you describe
| the database view of your application’s PSB to IMS Java. You must do this by
| providing the name of a metadata class when establishing the JDBC database
| connection.
| There are two ways you can prepare the metadata class for an application:
| v Provide the application PSB source and any related DBD source to the DLIModel
| utility, and specify the generation of the IMS Java metadata class.
| This is the recommended technique and is described in this chapter.
| v Code the metadata class manually.
| This is described further in Appendix A, “Manually Creating IMS Java Metadata
| Classes” on page 99.
| The DLIModel utility can process most types of PSBs and databases. For example,
| IMS Java supports:
| v All database organizations except MSDB, HSAM, SHSAM, and GSAM
| v All types and implementations of logical relationships
| v Secondary indexes except for shared secondary indexes
| v Secondary indexes processed as stand-alone databases
| v PSBs that specify field-level sensitivity
|
|
| Figure 30. The DLIModel Utility Inputs and Outputs
|
| Figure 30 shows the inputs and outputs of the DLIModel utility. The actions of the
| utility are directed by control statements that you supply. PSB and DBD source
| members are read from their PDS or PDSE data sets and parsed by the utility to
| build an in-memory object model of the database structure and the PSB’s view of
| that structure. Multiple PSBs may be processed in a single run of the utility.
| When these inputs have all been processed and incorporated into the model, the
| utility generates various outputs that were requested through control statements.
| You can request an XMI description of the entire in-memory model (one description
| covers all PSBs and DBDs processed in the run). For details of this XMI output, see
| “XMI Description of the Databases” on page 65.
| You can also request a detailed trace file of the utility execution if one is necessary
| for problem resolution.
|
| Requirements and Restrictions of the DLIModel Utility
| Requirements
| The following are the requirements to run the DLIModel utility.
| v PCBs in the PSB must be named, either through statement labels or the
| PCBNAME parameter.
| v If your application uses JDBC and the field list in a call includes fields from more
| than one segment in a hierarchic path, then IMS Java employs path calls. In this
| case you must include the PROCOPT=P option in the PCB or SENSEG
| statements, as appropriate.
| v If your application uses SSA database access, path calls are under your control,
| and you must choose PSB processing options depending on your processing, in
| the usual way.
| v This utility will not validate the PSB and DBD source. IBM strongly recommends
| that you generate DBDs, PSBs, and ACBs, correct all errors, and then run the
| DLIModel utility.
| v This utility follows all inter-DBD references when building its model, and may
| require access to DBDs that are not directly referenced by PCBs in the PSB. For
| example, when processing a PSB that references a main database with a
| number of secondary indexes, DLIModel needs access to the secondary index
| DBDs even if the PSB does not explicitly name any of these indexes for a
| secondary processing sequence, or for segment search purposes. Similarly, all
| DBDs related by logical relationships must be accessible.
| v You must maintain the length field in variable length segments on INSERT or
| UPDATE.
| v XMI input files must conform to the COBOL metamodel, which is part of the CAM
| metamodel of the OMG-accepted version of the UML specification for the
| Enterprise Application Integration (EAI) standard.
| Restrictions
| The DLIModel utility has the following restrictions. It cannot process:
| v MSDB, HSAM, SHSAM, and GSAM databases
| v Shared secondary indexes
| v PROCOPT=K option in a PSB SENSEG
| v The DLIModel utility does not use DLITypeInfoList classes in its generated
| classes. If you want to define repeating groups of fields in segments (other than
| by explicitly defining each group of fields separately) you will have to create the
| classes manually or modify the classes generated by DLIModel.
| Related Reading: For more information about IMS hierarchical databases, see
| the:IMS Version 7 Administration Guide: Database Manager and the IMS Version 7
| Utilities Reference: System.
|
| Output Types of the DLIModel Utility
| This section discusses the different output types of the DLIModel utility.
| Related Reading: For a description of the class source produced, refer to the
| Appendix A, “Manually Creating IMS Java Metadata Classes” on page 99.
| Related Reading: Sample DLIModel Java Reports are shown in each of the four
| examples in “Examples of Using the DLIModel Utility” on page 77.
| PSB Description
| Within the DLIModel Java Report, a separate section is produced for each PSB
| named in a PSB statement of the control data set. The name of the generated class
| for the PSB is given first, which is either the name defined by the JavaName
| parameter or, if no JavaName is specified, the 8-character IMS PSB name. The
| report also gives the IMS PSB name and the package for this class, if one was
| specified in the OPTIONS control statement.
| PCB Description
| Within each PSB, sections are listed for each PCB. Each PCB is identified by its
| IMS Java name, which is either the user-chosen JavaName, if one was specified, or
| the 8-character IMS PCB name. This is the PCB name that should be used in SQL
| queries to the database.
| Segment Description
| Within each PCB, all segments are listed in hierarchical sequence. Segment
| descriptions are indented to illustrate the hierarchical dependencies. Each segment
| is identified by its IMS Java name, which is either the JavaName, if one was
| specified in the control data set, or the 8-character IMS Segment name. Use the
| IMS Java name for the segment in SQL queries to the database.
| Field Description
| Within each segment, fields are listed in the order in which they appear in the
| database DBD with any additional fields appended. Fields are of the following
| types:
| Samples of the XMI produced (converted from UTF-8 to EBCDIC encoding for
| viewing in an OS/390 environment) for each of the samples in this chapter are in
| the samples directories. To use a sample XMI file as input for an application,
| convert the file back to UTF-8 encoding. You can also run the utility using the
| sample input files to generate XMI files written in UTF-8 encoding.
| The XMI that is produced by the utility is based on a meta-model of IMS database
| defined in UML. This model is a package with a number of inheritance relationships
| DLIModel Trace
| The DLI Model utility can generate a trace file, named dlimodeltrace, if you need to
| resolve a problem with the utility. For the utility to generate the trace file, specify
| GenTrace=YES in the OPTIONS statement. You can also specify the path where
| the file is written by using the TracePath parameter.
|
| Control Statements for the DLIModel Utility
| You must write control statements to specify certain options such as input and
| output data set names, and what PSBs and PCBs to use. You can also use the
| control statements to supply information to the utility about PSBs, PCBs, segments,
| and fields that cannot be extracted from the PSBs, DBDs, or COBOL copybook XMI
| files.
| The control statements are supplied to the utility in a PDS member named in the
| EXEC statement PARM field of the MVS JCL, or in an HFS file named in a
| command line parameter in the MVS USS environment.
| Optionally, you can include the following statements in the control data set:
| v PCB Statement
| v SEGM Statement
| v FIELD Statement
| v XDFLD Statement
| v INCLUDE Statement
| The following syntax diagram shows how to organize the control statements in the
| control data set.
|
|
QQ OPTIONS Statement \ PSB Statement \ Q
PCB Statement
|
|
Q \ QT
INCLUDE Statement
| If you requested IMS Java metadata class source in the OPTIONS statement, each
| PSB that you specified results in a separate metadata .java file, and a
| corresponding DLIModel Java Report.
| You do not need to include PCB, SEGM, or FIELD statements in your control
| statement set if all of the following statements are true of your application:
| v It can process PCBs, segments and fields by their 8-character IMS names.
| v It needs only fields that are defined in the DBD.
| v All fields can be processed as data type CHAR.
| Related Reading: For examples of control statement sets, refer to the examples in
| “Examples of Using the DLIModel Utility” on page 77.
| You can nest multiple control data sets by using the INCLUDE statement. Nesting
| gives you the flexibility to store your control statements across multiple HFS files or
| PDS members for increased convenience and control.
| For example, a top-level file could contain the OPTIONS, PSB and PCB statements
| that specify a desired Java-class generation. Included files might each contain a
| If your control statements are held in an MVS data set, map the statements to
| multiple 80-character records, between columns 1 and 72 inclusive. Columns 73
| through 80 are ignored, and may be used for sequence numbers if you wish. No
| continuation characters are required.
| If your control statements are held in an HFS file, any line length is acceptable, but
| you can optionally continue statements across multiple lines as in MVS. If you
| restrict your line length to less than 73 characters, your control statements can be
| moved between MVS data sets and HFS files without change.
| Identifiers, parameter keywords, and predefined parameter values (such as, YES
| and NO) may appear in upper or lower case. Other parameter values (for example,
| user specified path or Java names) are case sensitive.
|
|
QQ OPTIONS \ PSBds= IMS.qual.dsname(member) Q
|
|
Q \ DBDds= IMS.qual.dsname(member) Q
Package= packagename
| Q Q
| OutPath= path JavaSourcePath= path ReportPath= path
|
| PSBds=IMS.qual.dsname(member)
| Required parameter specifies the data set name of the PSB source. If multiple
| parameters are specified, the utility opens and searches the data sets in the
| order of the PDSds parameters when it is reading a PSB. This action is similar
| to data set concatenation in an MVS JVL DD statement.
| DBDds=IMS.qual.dsname(member)
| Required parameter specifies the data set name of the DBD source. If multiple
| parameters are specified, the utility opens and searches the data sets in the
| order of the DBDds parameters when it is reading a DBD. This action is similar
| to data set concatenation in an MVS JVL DD statement.
| Package=packagename
| Optional parameter specifies the package that the generated IMS Java classes
| are for. A Java package statement is added to each .java file produced.
| GenJavaSource=YES | NO
| Optional parameter specifies whether to generate IMS Java class source files
| and a DLIModel Java report.
| GenXMI=YES | NO
| Optional parameter specifies whether to generate an XMI file (dlimodelxmi.xmi)
| that describes the database model based on all PSBs and corresponding
| databases processed by the utility.
| GenTrace=YES | NO
| Optional parameter specifies whether to generate a trace file (named
| dlimodeltrace) of the utility run.
| OutPath=path
| Optional parameter specifies the HFS directory where the utility writes the
| output files, unless you specify path names for specific output files. The default
| is the current directory.
| JavaSourcePath=path
| Optional parameter specifies the HFS directory where the utility writes the IMS
| Java class files. Overrides OutPath.
| ReportPath=path
| Optional parameter specifies the HFS directory where the utility writes the
| DLIModel Java report. Overrides OutPath.
| XMIPath=path
| Optional parameter specifies the HFS directory where the utility writes the
| generated XMI. Overrides OutPath.
| TracePath=path
| Optional parameter specifies the HFS directory where the utility writes the trace
| file. Overrides OutPath.
| FieldOrder=DEFAULT | OFFSET
| Optional parameter specifies the order of the fields of segments in the
| generated IMS Java class.
| PSB Statement
| The PSB statement is required because it defines which PSBs that the utility uses.
| Multiple PSB statements are allowed, unless the * wildcard form is specified.
| PCB Statement
| The PCB statement is optional. It specifies a Java alias for a PCB. All PCB
| statements for a PSB must follow the PSB statement.
| SEGM Statement
| The SEGM control statement is optional and used for physical and logical
| segments.
| If the utility cannot find the segment, it issues a warning (instead of an error) and
| ignores any following FIELD statements. Because the utility only issues an error,
| you can create control statement files that provide information about many
| segments and their fields, not all of which are used by the particular PSB being
| processed.
| If an XMI COBOL copybook file was named for a segment, the fields that it defines
| are merged by name with the fields defined in the DBD.
| FIELD Statement
| The FIELD statement is optional. It specifies information about a field or defines a
| new field for a segment in a physical DBD. All FIELD statements for a segment
| must immediately follow the SEGM statement. However, FIELD statements can be
| in any order and mixed with XDFLD statements.
| When adding information for an existing DBD field, you must specify the 8-character
| DBD name of the field using the Name parameter. You can optionally specify the
| starting position (Start parameter) and length (Bytes parameter) of the field. If you
| do, DLIModel checks these values against the DBD and produces an error
| message if they do not match.
| To add information to a non-DBD field that has been inputted from COBOL
| copybook XMI file, specify a Java name (JavaName parameter) that matches the
| name of the copybook field. Do not specify a DBD 8-character field name (Name
| parameter). Not specifying a Name parameter, for example, to add a default value
| to a COBOL copybook field.
| To define a new field, you must specify the starting position (Start parameter), the
| length (Byte parameter) of the field, and the name (Name or JavaName parameter)
| of the field.
| QQ FIELD Q
| Name= name Start= int Bytes= name
| Q Q
| JavaName= name JavaType= string TypeQualifier= string
| Q QT
| Default= string
|
| Name=name
| Specifies eight-character field name as defined in the DBD. Must be unique
| within segment. Identifies this control statement as applying to an existing field
| within the DBD. Do not specify this parameter if you are specifying a new field.
| Start=int
| Specifies the starting position of the field in the segment. The first byte in the
| segment is 1. Required for new fields and optional for existing fields.
| Bytes=name
| Specifies the length of the field in the segment. Required for new fields and
| optional for existing fields.
| JavaName=name
| Specifies the Java alias for the field. Java names of Field statements and
| XDFLD statements must be unique within a segment. Required if defining a
| new field and optional for existing fields. If a field has been inputted from
| COBOL copybook XMI file with the same name as the JavaName parameter on
| a control statement, the control statement is applied to this COBOL copybook
| field.
| JavaType=string
| Optional parameter specifies the Java type of the field. Default is CHAR.
| Allowed types:
| CHAR
| FLOAT
| DOUBLE
| SMALLINT
| INTEGER
| BIGINT
| ZONEDDECIMAL
| TIME
| CARCHAR
| TINYINT
| BIT
| TYPELIST
| BINARY
| XDFLD Statement
| The XDFLD statement is optional. It specifies a Java alias for an existing secondary
| index field in a segment. The DXFLD statements must follow the SEGM statement
| that corresponds to the segment with the secondary indexes in the DBD.
| You must identify a secondary index field (which must be an existing field that was
| defined in the DBD) by the eight-character name because secondary index fields do
| not have a starting position in the segment. Secondary index fields do not have a
| data type. Therefore, you must create a single string that contains the concatenated
| search fields, each correctly encoded for its data type, when using the index field in
| a JDBC Select. An index field cannot be fetched from the JDBC Resultset.
| INCLUDE Statement
| The INCLUDE statement is optional and is only allowed in the top-level control
| statement data set. It specifies a PDS member or HFS file of additional control
| statements to be included in the top-level data set. The included data set must be
| the same type (PDS or HFS) as the top-level data set. You are allowed any number
| of INCLUDE statements in the top-level data set.
| Important: Do not put an INCLUDE statement between PSB statements and PCB
| statements or between SEGM statements and FIELD statements. Putting the
| INCLUDE statement between these statements breaks the required relationship
| between them.
| Comment Statement
| The Comment Statement is optional. It indicates that a line in the PDS member is a
| comment the same way as you would do in Java code. For example:
| // The two slashes indicate that this line is a comment.
|
| Running the DLIModel Utility
| You can run the DLIModel utility either as a standard OS/390 MVS job, or from the
| command prompt under MVS Unix System Services (USS). For the latter
| alternative, see “Running the DLIModel Utility From MVS Unix Systems Services”
| on page 77.
| Since the DLIModel utility is a Java application, the DLIMODEL procedure runs it on
| OS/390 using BPXBATCH, an MVS-provided utility that runs any OS/390 UNIX
| shell command or executable.
| The following is the DLIMODEL procedure, which runs the DLIModel utility:
|
|
| Figure 31. Sample DLIModel Utility PROC
|
|
| Step 1 DD Statements
| STDENV DD
| Contains statements that set the Java environment variables. You should
| not need to use this DD statement.
| STDOUT DD
| The destination to which the utility in STEP 1 directs standard output. This
| includes messages recording the normal execution of the utility. This output
| is redirected by STEP 2 to the standard MVS SYSOUT destination.
| Step 2 DD Statements
| SYSTEPRT DD
| IKJEFT01 utility output.
| HFSOUT DD
| Input from the temporary STDOUT file from step 1.
| HFSERR DD
| Input from the temporary STDERR file from step 1.
| STDOUTL DD
| Output destination for the STDOUT stream.
| STDERRL DD
| Output destination for the STDERR stream.
| SYSPRINT DD
| IKEJEFT01 utility output.
| SYSTSIN DD
| Must be added to execution JCL. Provides control statement input for the
| IKJEFT01 utility that redirect HFSOUT and HFSERR streams to the STDOUL
| and HFSERRL destinations. For example:
| OCOPY INDD(HFSOUT) OUTDD(STDOUTL)
| OCOPY INDD(HFSERR) OUTDD(STDERRL)
| As provided, the utility expects that you specify an HFS script file,
| /usr/lpp/ims/imsjava71/dlimodel/go, in its PARM= field. For details on whether this
| script file is required in your installation, how to prepare it, and alternatives, see
| “DLIModel Utility Setup” on page 19. Note that if a script file is required, its
| preparation is a one-time task. Once prepared it will be effectively invisible to users
| submitting the utility to MVS from ISPF.
| Related Reading: For more information about the MVS BPXBATCH utility, see
| OS/390: Unix Systems Services User’s Guide and OS/390: Unix Systems Services
| Command Reference.
| The command syntax for running the utility as a Java application is as follows:
|
| Figure 32. Physical DBD for Simple Example
|
|
| PCB1 PCB TYPE=DB,DBDNAME=DEALDB1,PROCOPT=A,KEYLEN=28
| SENSEG NAME=DEALER,PARENT=0
| SENSEG NAME=MODEL,PARENT=DEALER
| PSBGEN PSBNAME=AUTPSB1,LANG=ASSEM,CMPAT=YES
| END
|
| Figure 33. PSB for Simple Example
|
| Note that the PCB is given a name, as required by IMS Java. In this case a label is
| used, but a PCBNAME= parameter is also acceptable.
| A simple MVS JCL execution of the DLIModel utility, using this PSB and DBD, is
| shown in Figure 34.
|
| //BPXAUTP6 JOB CLASS=Z,MSGCLASS=E,MSGLEVEL=(1,1)
| //TEST EXEC DLIMODEL
| // DSNAME="DSNAME=IMSVS.TEST1.JCL(EXAMPLE1)"
| //STEP2.SYSTSIN DD *
| OCOPY INDD(HFSOUT) OUTDD(STDOUTL)
| OCOPY INDD(HFSERR) OUTDD(STDERRL)
| /*
|
| Figure 34. Minimal MVS JCL stream
|
| The control data set, DSNAME=IMSVS.TEST1.JCL(EXAMPLE1) is shown in
| Figure 35.
|
| Options GenJavaSource=yes
| PSBds=IMSVS.TEST1.PSBSRC
| DBDds=IMSVS.TEST1.DBDSRC
| PSB PSBName=AUTPSB1
|
| Figure 35. Control Data Set for Simple Example
|
| The utility processes a single PSB named AUTPSB1 and its DBD, DEALDB1. The
| utility reads the PSB and DBD from data sets IMSVS.TEST1.PSBSRC and
| IMSVS.TEST1.DBDSRC. It generates an IMS Java class only for this PSB, since
| no other output is requested. The name of the generated class is
| AUTPSB1DatabaseView (the first 7 characters of this name are set from the PSB
| name) and the class is written to the HFS file, AUTPSB1DatabaseView.java under the
| current directory. STDOUT is redirected to SYSOUT, but (in the absence of errors)
| The DLIModel Java Report, shown in Figure 36, describes the generated IMS Java
| metadata class AUTPSB1DatabaseView.
|
| DLIModel Java Report
| ========================
| Class: AUTPSB1DatabaseView generated for PSB: AUTPSB1
|
|
| ==================================================
| PCB: PCB1
| ==================================================
| Segment: DEALER
| Field: DLRNO Type=CHAR Start=1 Length=4 ++ Primary Key Field ++
| Field: DLRNAME Type=CHAR Start=5 Length=30 (Search Field)
| ==================================================
| Segment: MODEL
| Field: MAKE Type=CHAR Start=1 Length=10 ++ Primary Key Field ++
| Field: MODEL Type=CHAR Start=11 Length=10 (Search Field)
|
| Figure 36. DLIModel Java Report for Simple Example
|
| Notice these things in the DLIModel Java Report:
| v The class name, AUTPSB1DatabaseView, is based on the IMS PSB name.
| v The PCB name, PCB1, is the same as the label in the PSB PCB statement.
| v The segment names are the same as the names of the DBD SEGM statements.
| v The field names are the same as the names in the DBD FIELD statements.
| These names are all derived from the 8-character (maximum) names in the IMS
| PSB and DBD source members. These are the defaults that are used when no
| control statements or XMI COBOL copybook files are supplied to specify more
| developer-friendly names.
| Each field line displays the starting position and length of the field in the segment,
| and its type. Again, since there are no control statements or XMI COBOL copybook
| files to specify otherwise, the type of all fields defaults to CHAR.
| Each field in the example is annotated as either a primary key field, or a search
| field. Primary key fields are fields that were designated as a SEQ field in the DBD.
| Search fields are non-SEQ fields from the DBD. Both field types may be used in the
| WHERE clause of a JDBC statement, but Primary Key Fields generally provide a
| much faster response. In the example, these are the only field types, since there
| are no control statements or XMI COBOL copybook files to add additional fields,
| and no secondary indexes.
|
| Figure 37. EMPDB2 Physical DBD for Logical Relationship Example
|
|
| DBD NAME=DEALDB2,ACCESS=(HDAM,OSAM), X
| RMNAME=(DFSHDC40,1,5,200)
| DATASET DD1=DFSDLR
| SEGM NAME=DEALER,PARENT=0,BYTES=61
| FIELD NAME=(DLRNO,SEQ,U),BYTES=4,START=1,TYPE=C
| FIELD NAME=DLRNAME,BYTES=30,START=5,TYPE=C
| FIELD NAME=CITY,BYTES=10,START=35,TYPE=C
| SEGM NAME=MODEL,PARENT=DEALER,BYTES=37
| FIELD NAME=(MODKEY,SEQ,U),BYTES=24,START=3, X
| TYPE=C
| FIELD NAME=MODTYPE,BYTES=2,START=1,TYPE=C
| FIELD NAME=MAKE,BYTES=10,START=3,TYPE=C
| FIELD NAME=MODEL,BYTES=10,START=13,TYPE=C
| FIELD NAME=YEAR,BYTES=4,START=23,TYPE=C
| FIELD NAME=MSRP,BYTES=5,START=27,TYPE=P
| SEGM NAME=ORDER,PARENT=MODEL,BYTES=74
| FIELD NAME=(ORDNBR,SEQ,U),BYTES=6,START=1,TYPE=C
| FIELD NAME=LASTNME,BYTES=25,START=7,TYPE=C
| FIELD NAME=FIRSTNME,BYTES=25,START=32,TYPE=C
| FIELD NAME=DATE,BYTES=10,START=57,TYPE=C
| LCHILD NAME=(SINDXA,SINDEX2),POINTER=INDX
| XDFLD NAME=XFLD2,SRCH=(LASTNME,FIRSTNME,ORDNBR), X
| DDATA=DATE
| SEGM NAME=SALESPER,PARENT=((DEALER,),(EMPL,PHYSICAL,EMPDB2)),X
| BYTES=6, X
| POINTER=(LPARNT,LTWINBWD,TWINBWD), X
| RULES=(VVV)
| FIELD NAME=(EMPNO,SEQ,U),BYTES=6,START=1,TYPE=C (LPK)
| SEGM NAME=SALESINF,PARENT=SALESPER,BYTES=15
| FIELD NAME=QUOTA,BYTES=5,START=1,TYPE=C
| FIELD NAME=SALESYTD,BYTES=5,START=6,TYPE=C
| FIELD NAME=COMSSION,BYTES=5,START=11,TYPE=C
| DBDGEN
| FINISH
| END
|
| Figure 38. DEALDB2 Physical DBD for Logical Relationship Example
|
| In these two physical DBDs, note that segment, EMPL in EMPDB2 is a logical
| parent, and it is pointed to by physical logical child, SALESPER in DEALDB2. The
| Figure 39 shows a logical DBD based on these two physical DBDs. The logical
| DBD is rooted in the EMPDB2 physical DBD, and crosses the logical relationship to
| the DEALDB2 DBD via EMPSAL and DEALER to include the SALESINF segment
| from the DEALDB2 database. The EMPSAL and DEALER segments form a
| concatenated segment, with data from both physical segments present in the I/O
| area.
|
| DBD NAME=EMPLDB2,ACCESS=LOGICAL
| DATASET LOGICAL
| SEGM NAME=EMPL,PARENT=0,SOURCE=((EMPL,,EMPDB2))
| SEGM NAME=DEALER,PARENT=EMPL, X
| SOURCE=((EMPSAL,DATA,EMPDB2),(DEALER,DATA,DEALDB2))
| SEGM NAME=SALESINF,PARENT=DEALER, X
| SOURCE=((SALESINF,,DEALDB2))
| SEGM NAME=EMPLINFO,PARENT=EMPL, X
| SOURCE=((EMPLINFO,,EMPDB2))
| DBDGEN
| FINISH
| END
|
| Figure 39. Logical DBD for Logical Relationship Example
|
| Figure 40 shows a PSB, containing a single PCB that references this logical DBD.
| Note that field-level sensitivity is used in the logical segment, SALESINF. Only two
| of the three fields in that segment are visible. Also, in this example, the field lengths
| and start positions are specified so that there is an empty single byte between the
| two fields.
|
| PCB1 PCB TYPE=DB,DBDNAME=EMPLDB2,PROCOPT=A,KEYLEN=14
| SENSEG NAME=EMPL,PARENT=0
| SENSEG NAME=DEALER,PARENT=EMPL
| SENSEG NAME=SALESINF,PARENT=DEALER
| SENFLD NAME=QUOTA,START=1
| SENFLD NAME=SALESYTD,START=7
| SENSEG NAME=EMPLINFO,PARENT=EMPL
| PSBGEN PSBNAME=AUTPSB2,LANG=ASSEM,CMPAT=YES
| END
|
| Figure 40. PSB with Field-Level Sensitivity for Logical Relationship Example
|
| The JCL stream to execute the utility is similar to that presented in Figure 34 on
| page 78 of the previous Example 1.
| The minimal control data set presented in Example 1 could also work for this
| example. However, the control data set IMSVS.TEST1.JCL(EXAMPLE2) shown in
| Figure 41 on page 82 makes use of a few more control statements for purposes of
| illustration.
|
|
| Figure 41. Control Data Set for Logical Relationship Example
|
| The utility processes AUTPSB2, and the DBDs, DEALDB2 and EMPDB2. As
| already discussed, it reads the PSB and DBD from data sets,
| IMSVS.TEST1.PSBSRC and IMSVS.TEST1.DBDSRC. The JavaName parameter in
| the PSB statement sets the name of the generated class, and also determines the
| names of some of other output files. The utility generates an IMS Java class
| named, EmployeeView, and writes it to the HFS file, EmployeeView.java. A package
| statement is included in the class source to specify that the class is part of the
| package, example2.
| An XMI stream describing the data view of AUTPSB5 and its databases is
| generated and written to the file, xmiOutput.xmi. A trace of the execution is written
| to the file, dlimodeltrace. The DLIModel Java Report is written to the file,
| EmployeeViewJavaReport.txt. Since no paths are specified for these outputs, they
| are all written to the default directory in the HFS file system.
| Figure 42 shows the DLIModel Java Report from this execution. It matches the
| generated IMS Java metadata class (not shown).
|
| DLIModel Java Report
| ========================
| Class: EmployeeView in package: example2 generated for PSB: AUTPSB2
|
| ==================================================
| PCB: PCB1
| ==================================================
| Segment: EMPL
| Field: EMPNO Type=CHAR Start=1 Length=6 ++ Primary Key Field ++
| Field: LASTNME Type=CHAR Start=7 Length=25 (Search Field)
| Field: FIRSTNME Type=CHAR Start=32 Length=25 (Search Field)
| ==================================================
| Segment: DEALER
| Field: DLRNO2 Type=CHAR Start=1 Length=4 ++ Primary Key Field ++
| Field: DLRNO Type=CHAR Start=11 Length=4 (Search Field)
| Field: DLRNAME Type=CHAR Start=15 Length=30 (Search Field)
| Field: CITY Type=CHAR Start=45 Length=10 (Search Field)
| ==================================================
| Segment: SALESINF
| Field: QUOTA Type=CHAR Start=1 Length=5 (Search Field)
| Field: SALESYTD Type=CHAR Start=7 Length=5 (Search Field)
| ==================================================
| Segment: EMPLINFO
| Field: STATE Type=CHAR Start=51 Length=2 ++ Primary Key Field ++
| Field: ADDRESS Type=CHAR Start=1 Length=61 (Search Field)
| Field: STREET Type=CHAR Start=1 Length=25 (Search Field)
| Field: CITY Type=CHAR Start=26 Length=25 (Search Field)
|
| Figure 42. DLIModel Java Report for Logical Relationship Example
|
| There are three significant differences in this report as opposed to the preceding
| simple report shown in Figure 36 on page 79.
| v First, note that the layout of the DEALER segment reflects the fact that it is a
| concatenated segment. The first field, DLRNO2, is the destination parent
| Note that the segment ORDER in DEALDB2 has an XDFLD statement that defines
| a secondary index search field, XDFLD2, and that it has an LCHILD statement that
| references the secondary index database, SINDEX2 (as shown in the following
| fragment).
| LCHILD NAME=(SINDXA,SINDEX2),POINTER=INDX
| XDFLD NAME=XFLD2,SRCH=(LASTNME,FIRSTNME,ORDNBR), X
| DDATA=DATE
| The SRCH fields and the DDATA field named in the XDFLD statement all refer to
| fields in the ORDER segment itself, so in this example the source segment is the
| same as the target segment. However, this is not required by IMS Java.
|
| Figure 43. DBD for Secondary Index Example
|
| The logical database used by this example, Figure 44 on page 84 is based on
| DEALDB2, and does not cross any logical relationships.
|
|
| Figure 44. Logical DBD for Secondary Index Example
|
| The PSB is shown in Figure 45. The PROCSEQ= parameter in the PCB macro
| specifies a secondary processing sequence using the SINDEX2 secondary index.
|
| PCB1 PCB TYPE=DB,DBDNAME=DEALLDB2,PROCOPT=GR,KEYLEN=100, X
| PROCSEQ=SINDEX2
| SENSEG NAME=ORDER,PARENT=0
| SENSEG NAME=MODEL,PARENT=ORDER
| SENSEG NAME=DEALER,PARENT=MODEL
| PSBGEN PSBNAME=AUTPSB3,LANG=ASSEM,CMPAT=YES
| END
|
| Figure 45. PSB for Secondary Index Example
|
| This example is intended to be run from the USS prompt, instead of via JCL, as the
| previous examples were. A hypothetical command line is shown in Figure 46.
|
| > java com.ibm.ims.metagen.dlimodel ./ctlfiles/ctl1
|
| Figure 46. MVS USS Command for Secondary Index Example
|
| The control file, ./ctlfiles/ctl1 is shown in Figure 47.
|
| Options PSBds=IMSVS.TEST1.PSBSRC
| DBDds=IMSVS.TEST1.DBDSRC
| GenJavaSource=yes Package=example3
| GenXMI=yes GenTrace=yes
| PSB PSBName=AUTPSB3 JavaName=OrderView
| PCB PCBName=PCB1 JavaName=OrdersByName
|
| Figure 47. Control Data Set for Secondary Index Example
|
| In this control data set, a PCB control statement overrides the label in the IMS PCB
| statement (in the PSB shown in Figure 46) to a more descriptive name.
| The DLIModel utility generates the DLIModel Java Report in Figure 48 on page 85,
| together with a matching metadata class (not shown here).
|
|
| Figure 48. DLIModel Java Report for Secondary Index Example
|
| The difference between this Java Report and preceding examples is the presence
| of the secondary index in the ORDER segment. Note that the ORDER segment no
| longer has a primary key field, but instead has a field, XDFLD2, annotated as a
| ++Secondary Key Field++. This field can be used in the WHERE clause of a JDBC
| call and will function as a primary key field, providing fast response to queries.
| However, it is a virtual field and it cannot be retrieved from a result set by the
| application.
| In this example, where source and target segments are the same, the component
| search fields are also present in the ORDER segment, and so they could be
| retrieved as individual fields. In general, however, these fields may not be defined in
| the target segment, and so it would not be possible to retrieve them as individual
| fields.
| Note also that the component search fields of the secondary index field are listed in
| the report under the index field description. This information is intended to help the
| application developer construct suitable search strings for WHERE clauses that use
| the index field. In this example, since the source and target segments are the
| same, this information is readily available from the ORDER segment definition itself.
| However, in general these source fields may not be defined in the target segment,
| and may not even be present in the Java Report.
|
| Figure 49. Physical DBD for Multiple Control Statements Example
|
|
| DLR_PCB1 PCB TYPE=DB,DBDNAME=DEALERDB,PROCOPT=GO,KEYLEN=42
| SENSEG NAME=DEALER,PARENT=0
| SENSEG NAME=MODEL,PARENT=DEALER
| SENSEG NAME=ORDER,PARENT=MODEL
| SENSEG NAME=SALES,PARENT=MODEL
| SENSEG NAME=STOCK,PARENT=MODEL
| PSBGEN PSBNAME=DLR_PSB,MAXQ=200
| END
|
| Figure 50. PSB for Multiple Control Statements Example
|
| The example is executed from the MVS USS prompt, as shown in Figure 51.
|
| > java com.ibm.ims.metagen.dlimodel ./ctlfiles/ctl4
|
| Figure 51. MVS USS Command for Control Statements Example
|
| The top-level control statement file, ctl4, is shown in Figure 52 on page 87.
|
|
| Figure 52. Top-Level Control Data Set for Multiple Control Statements Example
|
| This control file establishes the options for the execution, as in previous examples,
| and directs the outputs (generated classes, java report, and trace) to a specified
| directory (outpath=gen). It also names the PSB to be processed, assigns a Java
| name for the generated class for this PSB, and provides a Java name for a PCB in
| that PSB.
|
| Figure 53. Second-Level Control Data Set for Multiple Control Statements Example
|
| Under the SEGM statement for DEALER, the first Field statement identifies an
| existing field, DLRNO, by both its DBD name and its start position and length.
| These facts will be checked for consistency against the DBD. If the field is identified
| correctly, then it is assigned a Java name, DealerNumber, and a data type, CHAR
| (which is the default, and therefore not necessary to specify).
| The second Field statement identifies an existing field by only its start position and
| length. If such a field exists, it is assigned the Java name, DealerName. This
| abbreviated method of identifying the field achieves the same result, but is not quite
| so safe because no 8-character name check is carried out. The data type for
| DealerName default is CHAR.
| The third Field statement under the DEALER SEGM statement defines a new field
| -- a field that is physically present in the segment, but is not described by a FIELD
| macro in the DBD. It specifies the start position and length of this field, assigns it a
| Java name of DealerAddress, and a type of CHAR.
| The remainder of the control statements describe information for the other
| segments and fields in the DBD in a similar manner. When DLIModel is executed, it
| generates the DLIModel Java Report in Figure 23, together with a matching
| metadata class (not shown here).
|
| DLIModel Java Report
| ========================
| Class: DealerDatabaseView generated for PSB: DLR_PSB
|
| ==================================================
| PCB: DealershipDB
| ==================================================
| Segment: DEALERxx
| Field: DealerNumber Type=CHAR Start=1 Length=4 ++ Primary Key Field ++
| Field: DealerName Type=CHAR Start=5 Length=30 (Search Field)
| Field: DealerAddress Type=CHAR Start=35 Length=50
| Field: YTDSales Type=PACKEDDECIMAL Type Qualifier=S9(18) Start=85 Length=10
| ==================================================
| Segment: MODELXX
| Field: ModelTypeCode Type=CHAR Start=1 Length=2 ++ Primary Key Field ++
| Field: CarMake Type=CHAR Start=3 Length=10 (Search Field)
| Field: CarModel Type=CHAR Start=13 Length=10 (Search Field)
| Field: CarYear Type=CHAR Start=23 Length=4 (Search Field)
| Field: Price Type=CHAR Start=27 Length=5 (Search Field)
| Field: EPACityMilage Type=CHAR Start=32 Length=4
| Field: EPAHighwayMilage Type=CHAR Start=36 Length=4
| Field: Horsepower Type=CHAR Start=40 Length=4
| ==================================================
| Segment: ORDERXX
| Field: OrderNumber Type=CHAR Start=1 Length=6 ++ Primary Key Field ++
| Field: PurchaserLastName Type=CHAR Start=50 Length=25 (Search Field)
| Field: PurchaserFirstName Type=CHAR Start=75 Length=25 (Search Field)
| Field: Options Type=CHAR Start=7 Length=30
| Field: Price Type=ZONEDDECIMAL Type Qualifier=99999 Start=37 Length=5
| Field: OrderDate Type=CHAR Start=42 Length=8
| Field: SerialNo Type=CHAR Start=100 Length=8
| Field: DeliverDate Type=CHAR Start=120 Length=8
| ==================================================
| Segment: SALESXX
| Field: DateSold Type=CHAR Start=1 Length=8 ++ Primary Key Field ++
| Field: PurchaserLastName Type=CHAR Start=9 Length=25 (Search Field)
| Field: PurchasetFirstName Type=CHAR Start=34 Length=25 (Search Field)
| Field: StockVINumber Type=CHAR Start=94 Length=20 (Search Field)
| Field: PurchaserAddress Type=CHAR Start=59 Length=25
| Field: SoldBy Type=CHAR Start=84 Length=10
| ==================================================
|
| Segment: STOCKXX
| Field: StockVINumber Type=CHAR Start=1 Length=20 ++ Primary Key Field ++
| Field: Color Type=CHAR Start=37 Length=10 (Search Field)
| Field: Price Type=CHAR Start=47 Length=5 (Search Field)
| Field: Lot Type=CHAR Start=53 Length=10 (Search Field)
| Field: DateIn Type=CHAR Start=21 Length=8
| Field: DateOut Type=CHAR Start=29 Length=8
|
| Figure 54. DLIModel Java Report for Multiple Control Statements Example
|
| In this DLIModel Java Report, the names of segments and fields are the Java
| names supplied in the control statements. The eight-character IMS names do not
| appear because the Java developer does not need to know these names.
In this Chapter:
v “Exceptions”
v “Sync Point Failure” on page 93
v “GU Message Failure” on page 93
v “Abends” on page 93
v “DLIModel Messages” on page 94
v “IMSTrace” on page 96
Exceptions
Exceptions are thrown as a result of non-blank status codes and non-zero return
codes (in cases when there were no PCBs to deliver status codes) from IMS DL/I
calls. Even though an exception is thrown by JavaToDLI for every non-blank status
code, some of these exceptions are caught by the application or database
packages and converted to return values.
DLIException extends IMSException. Exceptions of this type include all errors that
occur within the IMS Java library and are not a result of any call to IMS.
You can use the following methods to extract information from an IMSException:
getAIB
Returns the IMS AIB from the DL/I call that caused the exception. IMS AIB
is null for DLIException. The methods on the AIB can be called to return
other information at the time of the failure, including the resource or PCB
name and the PCB itself.
getStatusCode
| Returns the IMS status code from the DL/I call that caused the exception.
| This method works with the JavaToDLI set of constants. The status code is
| zero (0) for a DLIException.
getFunction
Returns the IMS function from the DL/I call that caused the exception.
Function is zero (0) for a DLIException.
try {
DealerDatabaseView dealerView = new DealerDatabaseView();
DLIConnection connection = DLIConnection.createInstance(dealerView);
connection.getUniqueSegment(dealerSegment, dealerSSAList);
} catch (IMSException e ) {
short statusCode = e.getStatusCode();
String failingFunction = e.getFunction();
}
Related Reading: For more information on DL/I Status Codes see IMS Version 7
Application Programming: Database Managerand IMS Version 7 Application
Programming: Transaction Manager.
SQLExceptions
SQLException is thrown to indicate that an error has occurred either in the Java
address space or during database processing.
A call to the sync point processor (DFSTMS00) returned a non-zero return code.
Contact your IMS system programmer.
| GU Message Failure
| If you receive a CR DL/I PCB status code, your IMS Java application GU message
| request call has failed. Table 7 describes the failure. Correct your application to
| issue a Java commit prior to issuing your next GU message call.
| Table 7. Status Code, Reason, and Return Code
| AIB PCB System Category Description
| Return/ Status Service
| Reason Code Call
| Code
| 0104/ CR IMS Java 4 Application error during GU message
| 0300 GU processing for an IMS Java application.
| Message
Abends
An abend is the abnormal ending of a program or application. When an abend error
condition occurs, an abend macro is issued either at the point of error detection or
by branching to a routine that issues the abend macro. There are also
pseudoabends in which the module that detects the error condition does not issue
the abend macro. Instead, it passes control back to the IMS call analyzer module,
DFSDLA00, which writes the contents of important control blocks to the system log
and indicates a dependent-region abend.
Following are the abends that you might encounter as a result of errors while
running IMS Java applications.
Processing Dumps
You might be asked to help interpret a dump for diagnostic purposes.
Related Reading:
v For more information on dump processing, see IMS Version 7 Installation
Volume 2: System Definition and Tailoring and IMS Version 7 Utilities Reference:
Database and Transaction Manager.
v For more information on dump analysis, see IMS Version 7 Failure Analysis
Structure Tables (FAST) for Dump Analysis and the IMS Version 7 Diagnosis
Guide and Reference.
| DLIModel Messages
| This section describes the messages that are issued by the DLIModel utility.
| The DLIModel utility message number severity suffixes are as follows unless
| otherwise indicated:
| E Unrecoverable error
| W Warning
| I Informational message
| |
| DHM0001 System Error: text (class/method) | DHM0002 through DHM0199 text (class/method)
| (DHM0001E) | (DHM0xxxE)
| Explanation: This message describes a probable error | Explanation: Messages in this range describe
| in the DLIModel utility during the import of a PSB or | problems in the input data that prevent the utility from
| DBD. | continuing during the import of a PSB or DBD. As a
| result, the utility terminates.
| text -describes the problem
| text -describes the problem
| (class/method)
| -describes the location; class or method name, | (class/method)
| in DLIModel at which the error was detected | -describes the location; class or method name,
| in DLIModel at which the error was detected
| (DHM00001E)
| -the message reference number | (DHM0xxxE)
| -the message reference number
| Programmer Response: Call IBM for service. Have
| these things available: | xxx the last three digits of the message
| v the content of this message | number, in the range: 2 through 199
| v the input PSBs and all related DBDs | Programmer Response: Typically, this error is the
| v control statement data set or file | result of incorrect or inconsistent PSB or DBD source
| data. It is strongly recommended that PSBs and DBDs
| v the JCL or USS command that you used to execute
| are compiled, an ACBGEN is performed, and all errors
| the utility
| are corrected before running the DLIModel utility. If
| Problem Determination: You may be asked to rerun | these tasks are not done, there is no guarantee that the
| DLIModel with the option parameter, Trace=yes set in | DLIModel utility will detect all potential errors in the PSB
| order to aid in the problem determination.
IMSTrace is distinct from the DLIModel utility trace. For information on how to set
the DLIModel utility trace, see “OPTIONS Statement” on page 68.
Initiating IMSTracing
| To debug with IMSTrace, you must first turn on the tracing function by setting the
| IMSTrace.traceOn variable to true. Because tracing does not occur until this
| variable is set, it is best to do so within a static block of your main application class.
| Then, you must decide how closely you want to trace the IMS Java library’s flow of
| control, and how much tracing you want to add to your application code.
You determine the amount of tracing in the IMS Java library by setting the value of
IMSTrace.libTraceLevel to one of its predefined values. By default, this value is set
to IMSTrace.TRACE_EXCEPTIONS, which traces the construction of
IMS-Java-library-provided exceptions. IMSTrace also defines constants for three
types of additional tracing. These constants provide successively more tracing from
IMSTrace.TRACE_CTOR1 (level one tracing of constructions) to
IMSTrace.TRACE_DATA3 (level three tracing of data).
finally {
if (IMSAuto.applicationTraceLevel >= IMSTrace.TRACE_METHOD2)
IMSTrace.currentTrace().logExit("IMSAuto.method1");
}
return result;
}
| Note: The recommended method for creating these classes is to use the DLIModel
| utility, described in Chapter 5, “DLIModel Utility” on page 61.
|
| Mapping an IMS Database in Java Classes
| To map an IMS database in Java classes, you use the segments and fields in the
| Database Definition (DBD) to create DLIDatabaseView and DLISegment
| subclasses. The hierarchical database shown in Figure 59 is used as the sample
| database in the code examples that follow.
|
| After the super() and any addDatabase() calls in the generated DLIDatabaseView
| subclass, a setString(), setInt(), or any setXXX() call can be made to set the
| default value. This default value remains constant throughout the application and so
| will exist in all cloned instances of the Segment.
| The following example demonstrates how to add a default value of Chris to the
| PersonalHero Field of the Employee Segment:
| The DB PCB defines the access rights that your application has to the segments of
| the database. In particular, a database PCB (PCB Type=DB) defines which
| segments, and which fields within those segments, your program can access, and
| the access intent (such as get, insert, replace, delete, or all) and isolation level
| (such as dirty read) that is used when accessing a database by way of that PCB.
|
| DBD NAME=DEALERDB,ACCESS=(HDAM,OSAM),RMNAME=(DFSHDC40.1.10)
| SEGM NAME=DEALER,PARENT=0,BYTES=94,
| FIELD NAME=(DLRNO,SEQ,U),BYTES=4,START=1,TYPE=C
| FIELD NAME=DLRNAME,BYTES=30,START=5,TYPE=C
| SEGM NAME=MODEL,PARENT=DEALER,BYTES=43
| FIELD NAME=(MODTYPE,SEQ,U),BYTES=2,START=1,TYPE=C
| FIELD NAME=MAKE,BYTES=10,START=3,TYPE=C
| FIELD NAME=MODEL,BYTES=10,START=13,TYPE=C
| FIELD NAME=YEAR,BYTES=4,START=23,TYPE=C
| FIELD NAME=MSRP,BYTES=5,START=27,TYPE=P
| SEGM NAME=ORDER,PARENT=MODEL,BYTES=127
| FIELD NAME=(ORDNBR,SEQ,U),BYTES=6,START=1,TYPE=C
| FIELD NAME=LASTNME,BYTES=25,START=50,TYPE=C
| FIELD NAME=FIRSTNME,BYTES=25,START=75,TYPE=C
| SEGM NAME=SALES,PARENT=MODEL,BYTES=113
| FIELD NAME=(SALDATE,SEQ,U),BYTES=8,START=1,TYPE=C
| FIELD NAME=LASTNME,BYTES=25,START=9,TYPE=C
| FIELD NAME=FIRSTNME,BYTES=25,START=34,TYPE=C
| FIELD NAME=STKVIN,BYTES=20,START=94,TYPE=C
| SEGM NAME=STOCK,PARENT=MODEL,BYTES=62
| FIELD NAME=(STKVIN,SEQ,U),BYTES=20,START=1,TYPE=C
| FIELD NAME=COLOR,BYTES=10,START=37,TYPE=C
| FIELD NAME=PRICE,BYTES=5,START=47,TYPE=C
| FIELD NAME=LOT,BYTES=10,START=53,TYPE=C
| DBDGEN
| FINISH
| END
|
| Figure 60. DBD Sample Definition
|
| The DLIDatabaseView subclass contains information from both the PSB and the
| DBD, including the following information:
| v The PSBNAME from the PSBGEN macro of the PSB definition
| v The PCB names of any PCB macros in the PSB definition
| v The segments defined for a PCB using the SENSEG macro of the PSB
| definition.
| v The fields defined within a segment. These are usually defined only within the
| DBD, but their use may be restricted by the SENFLD macro in the PSB
| definition. Figure 61 on page 102 shows the PSB definition for the Dealership
| application.
| DLIDatabaseView Example
| Using information from the PSB shown in Figure 61 on page 102, create a
| DLIDatabaseView subclass called DealerDatabaseView. The numbers in the
| following list (for example, 1) are referenced in Figure 61 on page 102. Note the
| following:
| v Within the subclass you create an array of DLISegmentInfo objects, one entry for
| each DLISegment object used by the application. 1 As you will see in
| “DLISegment Example” on page 103, a DLISegment object defines the fields in a
| database segment similar to the way an IMSFieldMessage object defines the
| fields in a message segment.
| v Each DLISegmentInfo object associates a DLISegment object to its parent. 2
| The parent is specified as a zero-based index in the array. Notice that the entry
| for the Order segment specifies an index of 1, which is the index in the array for
| the Model segment.
| v The parent of the root segment, Dealer, is specified by the constant
| DLIDatabaseView.ROOT to indicate that it has no parent. 3
| v The dealer PSB name, DLR_PSB, is passed in the DealerDatabaseView
| constructor to the super class constructor along with the array of DLISegmentInfo
| objects. 4
|
|
| Figure 61. DLIDatabaseView Example Code
| 102 IMS Java User’s Guide
| In our dealership example, there is only a single PCB defined in the dealership
| PSB. If there were other PCBs defined, they would be added to the
| DLIDatabaseView by:
| 1. Providing a separate array of DLISegmentInfo objects for the additional PCB.
| 2. Calling the method addDatabase within our Dealer constructor after the call to
| super, and passing the reference name of the PCB, the real name of the PCB,
| and the variable defining the array of DLISegmentInfo objects.
| DLISegment Example
| Using the extracted database name and segment names from Figure 60 on
| page 100, you create a DLISegment dealer. The numbers in the following list (for
| example, 1) are referenced in Figure 62. Note the following:
| v You create an array of DLITypeInfo objects, one entry for each field used by the
| application. 1
| v Each DLITypeInfo object defines the name, type, starting offset, length, and
| optionally the name of the field in the DBD. If you want to search on a field in a
| DLITypeInfo object, add the name of the field as specified in the DBD.
| You can have more fields than those named in the DBD. For example the field
| “DealerAddr” is a character field that starts at offset 35 for a length of 20 bytes
| and is not defined in the DBD. 2 To search on a field, the field name must be
| defined in the DBD file, and the field name as listed in the DBD must be provided
| to the DLITypeInfo object.
| v The segment name, DEALER, is passed in the Dealer constructor to the
| DLISegment constructor with the array of DLITypeInfo objects and the length of
| the entire array. 3 The easiest way to calculate that length is to add the starting
| offset of the last field in the array to its length and subtract 1. In this example: 55
| + 7 -1 = 61.
|
| static DLITypeInfo[] dealerInfo = { 1
| new DLITypeInfo("DealerNo", DLITypeInfo.CHAR 1, 4, "DLRNO"),
| new DLITypeInfo("DealerName", DLITypeInfo.CHAR 5, 30, "DLRNAME"),
| new DLITypeInfo("DealerAddr", DLITypeInfo.CHAR 35, 20),
| 2
|
| new DLITypeInfo("DealerCity", DLITypeInfo.CHAR 35, 10, "CITY"),
| new DLITypeInfo("DealerZip", DLITypeInfo.CHAR 45, 10, "ZIP")
| new DLITypeInfo("DealerPhone", DLITypeInfo.CHAR 55, 7, "PHONE"),
| };
| static DLISegment dealerSegment = new DLISegment("DealerSegment",
| "DEALER", dealerInfo, 61); 3
|
| Figure 62. Example DLISegment Code
|
In this chapter:
v “Compile and Runtime Options”
v “Installation Verification Process” on page 107
-main=classname
Use this option to specify the class that contains the main startup method,
which is used as the main entry point for the executable.
-make Use this option to rebind only those objects that have changed. Although
you can use the -make option when building a Java executable or DLL for
the first time, you normally use this option when you are doing incremental
rebind to refresh an existing Java executable or DLL.
-target=IMS
Use this required option to indicate that the program will be an IMS
application.
-o=executable
Use this option to explicitly name the Java executable or DLL that you are
building in the hfs file system or as a PDSE (partitioned dataset extended)
member.
-alias=name
Use this option to specify an alias or hierarchical file system (HFS), such as
the name for a Java executable or DLL that is being written to a PDSE
member. The option -alias must be specified for all Java DLLs that reside in
PDSE members.
The HLQ (High Level Qualifier) is the PDSE that you specified during the
installation process for IMS Java.
6. Change the version number of the HPJ to reflect the correct version of HPJ
installed.
7. Submit the JCL to start the IMS MPP region.
8. Go to the IMS terminal and invoke the formatted screen for the transaction:
/format IVTCC
SEGMENT# :
9. Enter the appropriate input. Figure 66 shows an example for the display query:
Figure 67 on page 109 displays the output of the transaction:
**************************************************
* IMS INSTALLATION VERIFICATION PROCEDURE *
**************************************************
SEGMENT# :
Figure 66. Example IMS Installation Procedure Screen with Transaction Input Information
Figure 67. Example IMS Installation Verification Procedure Screen with Transaction Output
Information
Index 115
java message processing (JMPs) 45 message processing application
JAVA_HOME 16 building 46
java.math.BigDecimal 32 message processing applications 46
java.sql.Connection 30 message queue 46
java.sql.DatabaseMetaData 31 message switch input 46
java.sql.Date 32 messages
java.sql.Driver 31 input
java.sql.PreparedStatement 32 defining 47
java.sql.ResultSet 32 processing multiple 56
java.sql.ResultSetMetaData 32 retrieving 56
java.sql.Statement 31 message queue in Java 46
java.sql.Time 32 multi-segment 54
java.sql.Timestamp 32 output, defining 47
JAVAENV data set 16 reading and writing 46
JBP (Java Batch Processing) repeating structures
configuring 5 accessing 55
overview 2 SPA 52
JBPs 45 metadata class
JDBC creating 24
classes 27 metadata classes
Connection object, returning 29 creating 61
data types 32 creating manually 99
field names 27 generated 64
IMS databases multi-segment messages 54
accessing 24
interfaces, limitations 30
overview 1, 23 N
prerequisite knowledge xv naming conventions
JMP (Java Message Processing) SQL 35
configuring 4 nested structures
overview 2 accessing 55
JMPs 45
JVM
master 4 O
worker 5 object
JVM regions, overview 1 DLIConnection 41
JVMOPMAS 4 DLIConnection, creating 42
JVMOPWRK 5 DriverManager 30
java.sql.Connection 30
SSA 41
K ODBA (Open Database Access) 9
keywords options
aggregate 35 include 105
supported 35 Options statement 66, 68
output messages
defining 47
L
LIBPATH 16
local transactions 3 P
logical relationships P processing option 3
DLIModel utility example 79 package
logical terminal (LTERM) 54 database 30
long data type 32 PACKEDDECIMAL data type 32
LTERM 54 PARM parameter 75
path call 38
PCB statement 67
M prepared statement 40
main storage buffers 46 PreparedStatement object 29, 36
main() 48 prerequisite knowledge xv
master JVM 4 problem determination 91
PROC statement parameters 75
Index 117
tracing (continued)
IMSTrace 96
Trace statements, adding 97
transaction message input 46
transactions
conversational 52
local 3
turning on IMSTrace 96
types
data, mapped to COBOL 33
supported 32
U
UPDATE statement 39
URL (universal resource locator) 30
USS (Unix System Services)
DLIModel utility, running 21
V
VARCHAR data type 32
W
WebSphere for z/OS
DRA startup table 9
EJB, deploying 9, 11
IMS JDBC Resource Adapter 9
J2EE server 2
ODBA 9
WebSphere for z/OS environment
accessing IMS 9
configuring 9
DRA startup table 9
installation verification 12
overview 2
restrictions 8
setup 8
system requirements 8
WHERE clause 38
worker JVM 5
X
Xdfld statement 73
XMI
creating 61
metamodel 65
XOPEN SQLstate 92
Z
ZONEDECIMAL data type 32
Overall, how satisfied are you with the information in this book?
How satisfied are you that the information in this book is:
When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any
way it believes appropriate without incurring any obligation to you.
Name Address
Company or Organization
Phone No.
___________________________________________________________________________________________________
Readers’ Comments — We’d Like to Hear from You Cut or Fold
SC27-0832-02 Along Line
_ _ _ _ _ _ _Fold
_ _ _and
_ _ _Tape
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Please
_ _ _ _ _do
_ _not
_ _ staple
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Fold
_ _ _and
_ _ Tape
______
NO POSTAGE
NECESSARY
IF MAILED IN THE
UNITED STATES
IBM Corporation
H150/090
555 Bailey Avenue
San Jose, CA
95141-9989
_________________________________________________________________________________________
Fold and Tape Please do not staple Fold and Tape
Cut or Fold
SC27-0832-02 Along Line
Printed in U.S.A.
SC27-0832-02
Spine information: