SG 248116
SG 248116
SG 248116
Implementing a practical
example
Zaid Faydi
Alex Louwe Kooijmans
Elsie Ramos
ibm.com/redbooks
International Technical Support Organization
May 2013
SG24-8116-00
Note: Before using this information and the product it supports, read the information in “Notices” on page v.
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .v
Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vi
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Authors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . vii
Now you can become a published author, too! . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii
Comments welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii
Stay connected to IBM Redbooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . viii
Related publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
IBM Redbooks publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Other publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Online resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Help from IBM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
This information was developed for products and services offered in the U.S.A.
IBM may not offer the products, services, or features discussed in this document in other countries. Consult
your local IBM representative for information on the products and services currently available in your area. Any
reference to an IBM product, program, or service is not intended to state or imply that only that IBM product,
program, or service may be used. Any functionally equivalent product, program, or service that does not
infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to
evaluate and verify the operation of any non-IBM product, program, or service.
IBM may have patents or pending patent applications covering subject matter described in this document. The
furnishing of this document does not grant 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.
The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION
PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of
express or implied warranties in certain transactions, therefore, this statement may not apply to you.
This information could include technical inaccuracies or typographical errors. Changes are periodically made
to the information herein; these changes will be incorporated in new editions of the publication. IBM may make
improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time
without notice.
Any references in this information to non-IBM websites are provided for convenience only and do not in any
manner serve as an endorsement of those websites. The materials at those websites are not part of the
materials for this IBM product and use of those websites 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.
Any performance data contained herein was determined in a controlled environment. Therefore, the results
obtained in other operating environments may vary significantly. Some measurements may have been made
on development-level systems and there is no guarantee that these measurements will be the same on
generally available systems. Furthermore, some measurements may have been estimated through
extrapolation. Actual results may vary. Users of this document should verify the applicable data for their
specific environment.
Information concerning non-IBM products was obtained from the suppliers of those products, their published
announcements or other publicly available sources. IBM has not tested those products and cannot confirm the
accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the
capabilities of non-IBM products should be addressed to the suppliers of those products.
This information contains examples of data and reports used in daily business operations. To illustrate them
as completely as possible, the examples include the names of individuals, companies, brands, and products.
All of these names are fictitious and any similarity to the names and addresses used by an actual business
enterprise is entirely coincidental.
COPYRIGHT LICENSE:
This information contains sample application programs in source language, which illustrate programming
techniques on various operating platforms. You may copy, modify, and distribute these sample programs in
any form without payment to IBM, for the purposes of developing, using, marketing or distributing application
programs conforming to the application programming interface for the operating platform for which the sample
programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore,
cannot guarantee or imply reliability, serviceability, or function of these programs.
The following terms are trademarks of the International Business Machines Corporation in the United States,
other countries, or both:
CICS® Rational® WebSphere®
DB2® Redbooks® z/OS®
IBM® Redbooks (logo) ®
MVS™ System z®
Windows, and the Windows logo are trademarks of Microsoft Corporation in the United States, other
countries, or both.
Java, and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its
affiliates.
UNIX is a registered trademark of The Open Group in the United States and other countries.
Other company, product, or service names may be trademarks or service marks of others.
Mainframe computers play a central role in the daily operations of many of the worlds largest
corporations. Batch processing is still a fundamental, mission-critical component of the
workloads that run on the mainframe and a large portion of the workload on IBM® z/OS®
systems is processed in batch mode.
This IBM Redbooks® publication is the second volume in a series of four in which we
describe new technologies introduced by IBM to facilitate the use of hybrid batch applications
that combine the best aspects of Java and procedural programming languages such as
COBOL. This volume specifically focuses on z/OS batch runtime.
The audience for this book includes IT architects and application developers, with a focus on
batch processing on the z/OS platform.
Authors
This book was produced by a team of specialists from around the world working at the
International Technical Support Organization, Poughkeepsie Center.
Zaid Faydi is a Software Engineer who is currently Test Manager at CSC in Perth, Australia.
Previously he worked at IBM for 6 years. His areas of expertise include z/OS application
quality assurance and Java programming.
Alex Louwe Kooijmans is a Senior Architect at the Financial Services Center of Excellence
at IBM Systems and Technology Group. Prior to this position, he spent almost 10 years in the
International Technical Support Organization leading IBM Redbooks projects, teaching
workshops, and running technical events with a focus on using the IBM mainframe in new
ways. Alex also worked as Client Technical Advisor to various banks in the Netherlands and
performed several job roles in application development. His current focus is on modernizing
core banking systems and the role of IBM’s current mainframe technology.
Gary Puchkoff
Software Architect, IBM Systems and Technology Group. z/OS New Technology
IBM Poughkeepsie, USA
Find out more about the residency program, browse the residency index, and apply online at:
ibm.com/redbooks/residencies.html
Comments welcome
Your comments are important to us!
We want our books to be as helpful as possible. Send us your comments about this book or
other IBM Redbooks publications in one of the following ways:
Use the online Contact us review Redbooks form found at:
ibm.com/redbooks
Send your comments in an email to:
[email protected]
Mail your comments to:
IBM Corporation, International Technical Support Organization
Dept. HYTD Mail Station P099
2455 South Road
Poughkeepsie, NY 12601-5400
In this chapter, we introduce the concept of hybrid batch applications and discuss the benefits
of using Java in combination with COBOL. We also introduce the z/OS Batch Runtime, a new
z/OS V1.13 base component, which facilitates development and deployment of hybrid
Java/COBOL applications without the requirement of having IBM WebSphere®, IBM CICS®
or any other container. This provides hybrid COBOL/Java batch applications with the
capability to share an IBM DB2® connection and execute transactions as a single unit of work
(UOW).
Refer to Batch Modernization on z/OS, SG24-7779 for a broad discussion about the benefits
of using Java in an existing z/OS environment.
1.3.1 Skills
In the z/OS environments of today, many organizations want to re-engineer existing native
z/OS COBOL applications to incorporate Java in order to benefit from its larger developer skill
base and its many language features. Companies want to take advantage of the existing
Java skills to create new batch applications because they can easily find the people and
resources needed to make those applications a success. At the same time, it does not make
business sense to rewrite existing COBOL applications. Therefore, there is the need to
integrate Java and procedural languages such as COBOL in a seamless manner.
Procedural languages such as COBOL are good at manipulating data, reading and writing
records from z/OS resources such as VSAM files and relational databases. It might make
sense to call out from a modern Java batch application to a COBOL routine to manipulate
data and access the z/OS resources that are needed for the batch job.
When the benefits of two or more programming languages are combined, the result is called
a hybrid application. This extended functionality can increase the complexity and present
some domain-specific pitfalls. One such pitfall is the loss of transactional integrity when a unit
of work spans different components. For example, a COBOL application issues an UPDATE
change to a DB2 table, then invokes Java code that will issue another required UPDATE to
the same resource. If the UPDATE in the Java code fails, the COBOL UPDATE will not be
rolled back because the two transactions where not defined as a single unit of work.
Natively, executing as a single transaction across more than one database connection
increases the complexity of your code because transaction checking and failure recovery
logic must be added.
To extend a batch database COBOL application with Java functionality and also ensure data
integrity, consider using the z/OS Batch Runtime. In a nutshell, this container offers a
managed environment in which to execute a hybrid Java/COBOL program as a single unit of
work. A single connection to a local database is established at startup and is shared across
both the Java and COBOL portions of the program. Commit and rollback services are
available to your program to either discard your changes or make them permanent.
This book provides a detailed discussion of this container. It also covers design
considerations and provides a development scenario to illustrate how this container can be
used to extend a batch COBOL application with Java functionality using the modern
development tooling of IBM Rational® Developer for System z.
The z/OS Batch Runtime initializes the environment for COBOL and Java interoperability by
doing the following:
Setting up the job step under a Resource Recovery Services (RRS) managed global
transaction
Calling the primary COBOL or Java application after initialization of the environment.
Refer to Batch Modernization on z/OS, SG24-7779, for further details about z/OS Batch
Runtime and the updates in z/OS 1.13 to improve BATCH job processing.
Transaction Execution
Submit Service Service
JCL BCDBATCH
JES z/OS Plugin z/OS Plugin
Proc
z/OS Batch
Container Policy/logs
Process Job Step
Commit
Rollback
JDBC JAVA/Cobol App
Local DB2
The z/OS Batch Runtime provides an environment where your DB2 COBOL and Java
applications can share a single database connection. The z/OS Batch Runtime also provides
commit/rollback services by leveraging the z/OS Resource Recovery Services (RRS) and the
Java Database Connectivity (JDBC) driver.
In your JCL, you must specify the Java archive (JAR) and dynamic link library (DLL) files
necessary to run your primary application and the z/OS Batch Runtime.
The z/OS Batch Runtime configuration options are defined in the BCDIN data definition name
(DDNAME). To specify the primary application, set the bcd.applicationName option to the
name of your application and specify the programming language in bcd.applicationLanguage
(Refer to Example 2-1).
Note: Only COBOL and Java are currently supported in this release.
To pass a string array to your main Java application method, use the same option and
increment the index for each element, as shown in Example 2-2.
RecordManager class
The RecordManager class contains the simple main method shown in Example 2-3.
Note: The bcd.applicationArgs option can be omitted from the JCL without affecting the
application or the run time if no references are made to the application arguments.
Return code and exception handling by the primary application is important to ensure an
accurate representation of execution. Both need to be programmatically implemented and
taken into consideration when designing hybrid applications. The primary application decides
the final return code to send based on its own processing and the values returned from the
applications it called.
Generally, the highest return code is cascaded to the primary application and returned. For
example, a COBOL application that calls a Java method that returns an integer value needs
to move this value to the return-code register if it is higher than the current return-code value.
If the Java return value is a boolean and denotes the success of execution, then one possible
implementation is to set the COBOL return code register to 12 only if the value is false.
Failure to handle return values from other components returns the value of the return-code
register upon completion of a COBOL primary application, which in some cases might not
reflect the overall execution of the application.
If the called Java method has an exception during processing that the COBOL primary
application does not handle, then the container terminates with a return code of 12. Not all
exceptions warrant a return code of 12; therefore, handling them appropriately is essential. It
requires the primary application to decide whether an exception should cause the container
to return a 0 or an 8. Despite that an exception occurred, the action was successful, so a
return code of 0 can be returned, as well as a log message to warn about the cause of the
exception.
Example 2-8 provides a simple code snippet of a COBOL application that handles the return
value of a Java method and checks to see if an exception has occurred.
Example 2-8 Sample code to handle return code and exceptions from Java
* Calling the returnRC Java method
DISPLAY 'COBOL: Calling returnRC with parameter' INPUT-VALUE
INVOKE DemoJava "returnRC"
USING BY VALUE Parameter
RETURNING RC
IF RC > RETURN-CODE THEN
MOVE RC TO RETURN-CODE.
PERFORM EXCEPTION-CHECK.
GOBACK.
MAIN-FINISH.
* Checks if an Exception has occurred
EXCEPTION-CHECK.
CALL ExceptionOccurred
USING BY VALUE JNIEnvPtr
RETURNING JavaException
IF JavaException NOT = NULL THEN
CALL ExceptionClear
USING BY VALUE JNIEnvPtr
Rather than implementing your own two-phase commit protocol in your hybrid applications,
you can exploit the resource managers provided by the z/OS Resource Recovery Services
(RRS). RRS is a general global sync point manager, and a component of z/OS that allows
applications to guarantee that data changes have been made or backed out of a resource,
such as a DB2 database.
The Java Database Connection (JDBC) is a resource manager that exploits RRS to read and
change database data, and take actions such as committing or backing out changes.
The z/OS Batch Runtime implements RRS and JDBC calls to provide your applications with
helper methods to simplify the usage of commit rollback. The commit and rollback methods
reside in the com.ibm.batch.spi.UserControlledTransactionHelper. The use of these
helper methods is illustrated in “End-to-end development scenario” on page 17.
Note: Only local DB2 databases are supported in this release because applications and
DB2 resources must exist on the same z/OS image.
A new thread or TCB created that executes a database transaction is not identified as a z/OS
Batch Runtime transaction. A new attachment is created and any transaction executed is out
Cleanup processing
If the application terminates with an unhandled exception or an abend, then the z/OS Batch
Runtime rolls back all the outstanding database changes. Otherwise, it commits them
regardless of the return code.
The JCL that invokes z/OS Batch Runtime invokes the job BCDBATCH. BCDBATCH, in turn,
invokes the JZOS launcher to initialize the Java environment.
Because BCDBATCH invokes JZOS, one level of the JZOS launcher exists for each Java
SDK level and bit mode. You define the level with a symbolic, and your installation can
update the symbolic as new levels of the Java SDK are added or made the default.
Sample BCDBATCH and BCDIN JCLs with explanations are available in Chapter 2 of z/OS
Batch Runtime: Planning and User’s Guide, SA23-7270.
Note: A current sample of the BCDBATCH job for z/OS Batch Runtime is always available
in SYS1.SAMPLIB in the latest z/OS release.
You must also configure the CLASSPATH and LIBPATH variables with the list of Java
archive (JAR) files and dynamic link library (DLL) files that are required to run both the z/OS
Batch Runtime and the application.
2.5 Restrictions
The following list identifies the limitations and restrictions on running the z/OS Batch Runtime:
Updates to multiple databases are not supported; only one local database attachment is
created and used by all applications running in the batch container.
Only 31-bit EBCDIC applications are officially supported.
A 31-bit version of the Java Virtual Machine (JVM) must be used.
Multi-threaded Java DB2 applications are not supported.
Java System.exit and COBOL STOP BACK calls cannot be used because they prevent the
z/OS Batch Runtime from gaining control of the thread/TCB. Use GOBACK instead in your
COBOL applications.
COBOL applications must not code RRS Attach Facility (RRSAF) calls to initialize or end
a DB2 connection. This can affect the DB2 connection managed by the z/OS Batch
Runtime.
There is no support for multiple resource managers; currently only JDBC is available.
When compiling and linking an application with embedded static SQL statements, you must
precompile and bind it. The precompiler converts the SQL statements into a form that the
database manager understands and stores them into a bind file. The binding process creates
a package from a bind file that the database manager uses to access the database when the
application is run.
When designing your application for optimal performance, you must carefully decide whether
to use static or dynamic SQL statements. The intended usage and working environment
generally dictates this choice. The execution time of both these types of statements should be
equivalent after they are compiled. Applications using dynamic SQL statements will require a
higher initial cost per SQL statement because they need to be compiled before use. Despite
the higher cost, dynamic SQL statements in some cases can run faster due to better access
plans being chosen by the optimizer. The cost of compiling dynamic SQL statements can also
vary because the statements might be implicitly recompiled by the system while the
application is running.
Sometimes there is no obvious decision and it is best to choose the method you are most
comfortable with. Table 2-1 is extracted from IBM DB2 Universal Database Application
Development Guide: Programming Client Applications, SC09-4826 and provides guidelines
for choosing which approach to use.
Data Uniformity
Uniform data distribution Static
Slight non-uniformity Either
Highly non-uniform distribution Dynamic
Repetitious Execution
Runs many times (10 or more times) Either
Runs a few times (less than 10 times) Either
Runs once Static
Nature of Query
Random Dynamic
Permanent Either
Frequency of RUNSTATS
Very infrequently Static
Regularly Either
Frequently Dynamic
As mentioned in “Sharing a DB2 connection” on page 10, during startup, the z/OS Batch
Runtime establishes a connection with the specified local database so that the applications
running in the container can communicate with that database without having to create their
own new connection.
Your Java applications must use the Connection class in the java.sqlpackage and pass the
URL String jdbc:default:connection to get the database connection (Example 2-11).
If this batch container meets your requirements and your applications are not affected by its
limitations, then the following simple code changes are required:
Remove all thread/TCB terminating calls – System.exit and STOP BACK, see “Terminating
managed applications” on page 10.
In your Java code, ensure the DriverManager getConnections method uses the URL
jdbc:default:connection to get the existing connection to the local database system.
Write and configure the z/OS Batch Runtime options in your JCL to invoke the application
and the container.
We also demonstrate how to extend an existing stand-alone batch DB2 COBOL application
with new Java functionality. Samples of the source code and JCL are provided to illustrate the
changes required to run the modified COBOL application in z/OS Batch Runtime.
We used a step-by-step format and included screen shots that should be helpful for users
who might not be familiar with Integrated Development Environments (IDEs) such as Eclipse.
3.2.2 Java
The output from the BCPIVP program shows the level of Java installed.
However, if you are having difficulties running the JCL and want to do dome troubleshooting,
this is another way to check whether the required version and level of Java is installed on
your system:
Enter the OMVS shell
From ISPF, enter TSO OMVS
At the console, enter java -version
To download and learn more about z/OS Java Technology Edition, refer to:
http://www-03.ibm.com/systems/z/os/zos/tools/java/products/sdk601_31.html
2. Select z/OS as the System type and click Next (Figure 3-2).
7. If prompted with the window shown in Figure 3-7, click Yes to proceed.
8. To confirm that you are connected and that your MVS and HFS subsystem information is
correct, expand the z/OS UNIX Files and MVS Files nodes and their child nodes. Expand
the JES node and confirm that a list of jobs is returned. If a list is not returned, then it might
be that you have no jobs to retrieve or you need to set the correct JES Job Monitor port
number, as shown in Figure 3-8. To correct the setting, right-click the JES node and select
Properties.
2. Enter com as the folder name and click Finish (Figure 3-10).
3. Create a folder called sample under the newly created com folder, then create lib, src and
statements folders under sample, as shown in Figure 3-11 on page 25.
3.3.3 Creating the z/OS project and MVS and UNIX subprojects
Use the following steps to create the z/OS project and MVS and UNIX subprojects.
1. In the z/OS Projects view, right-click and select z/OS Project (Figure 3-12).
2. Enter BatchProject as the Project name, ensure that the Create an MVS subproject radio
button is selected, then click Finish (Figure 3-13).
4. You also need a UNIX subproject for your new Java code. To create a UNIX subproject,
right-click the BatchProject node and select New z/OS UNIX Subproject. The New
z/OS UNIX Subproject wizard appears. Select BatchProject as the parent project and
click Next (Figure 3-15).
6. Click the Remote Working Directory Browse button, navigate to the sample folder you
created earlier, and click OK (Figure 3-17).
8. Specify a filter for this new subproject. Enter sample as the filter name and click Next
(Figure 3-19).
2. In the Data Source Explorer, click the New Connection button (Figure 3-24).
4. Click Test Connection and confirm that the New Connection window appears with the
message Connection succeeded (Figure 3-26).
6. Before you can add the SQL statements to create the sample table, you must create a
new Data Set Project. Right-click in the Data Project Explorer and select New Data
Design Project (Figure 3-28).
8. To create a new SQL Script, expand the newly created BatchProjectData node, right-click
SQL Scripts, and select New SQL or XQuery Script (Figure 3-30).
9. Name the SQL script CreateQueriesTable and click Finish (Figure 3-31).
11.An editor is opened. Copy the SQL statements shown in Example 3-4 into the editor.
13.Right-click the newly created CreateQueriesTable.sql SQL script and click Run SQL
(Figure 3-34).
15.In the SQL Results view you should see a successful execution and the table created
under the Schemas SQLID Tables node in the Data Source Explorer view
(Figure 3-36).
17.From this editor, you can insert or delete records and set field data; for now, leave it as is
(Figure 3-38).
3. Enter ITSO as the filter name and click Finish (Figure 3-41).
5. To allocate data sets, right-click CobolSubProject in the z/OS Projects view and select
New Allocate Partitioned Data Set (Figure 3-43).
6. Enter ITSO.COBOL in the Data Set Name textbox and click Next (Figure 3-44).
8. The <HLQ>.ITSO.COBOL data set is now allocated and should appear under
CobolSubProject and the ITSO filter under MVS Files in the Remote Systems view,
created earlier (Figure 3-46).
COBLOAN is a simple stand-alone batch COBOL application that calculates the monthly
repayments of a loan given the principle amount, fixed interest rate, and number of periods
the interest is charged. The amount is displayed in the job output and all values are inserted
into a DB2 table for record keeping.
PdfCreator is a Java class that implements a new business requirement to generate Portable
Document Format (PDF) files of each calculation. The path of the PDF file generated is
stored in the same table COBLOAD uses. The two database transactions from COBLOAN
and PdfCreator are set to be a single unit of work. If either transaction fails, both changes are
discarded.
For your convenience, we have provided the source files for this scenario. If you want to
reproduce the development scenario without having to copy/paste the source code out of this
chapter, you can FTP the files described in “Using the Web material” on page 63 to your
system.
3. COBLOAN will be created under <HLQ>.ITSO.COBOL with a .cbl extension, which is not
set on the host. Double-click this new member to invoke the editor and copy the COBOL
code shown in Example 3-5.
CONFIGURATION SECTION.
REPOSITORY.
Class PdfCreator is "PdfCreator"
Class jstring is "jstring".
DATA DIVISION.
WORKING-STORAGE SECTION.
01 FIELDS.
05 PAYMENT PIC S9(9)V99 USAGE COMP.
05 PAYMENT-OUT PIC $$$$,$$$,$$9.99 USAGE DISPLAY.
05 LOAN-AMOUNT PIC S9(7)V99 USAGE COMP.
05 LOAN-AMOUNT-IN PIC X(16).
05 INTEREST-IN PIC X(5).
05 INTEREST PIC S9(3)V99 USAGE COMP.
05 NO-OF-PERIODS-IN PIC X(2).
05 NO-OF-PERIODS PIC 99 USAGE COMP.
01 RC PIC S9(9) COMP-5.
01 parmString OBJECT REFERENCE jstring.
LINKAGE SECTION.
01 INPUT-PARM.
05 INPUT-LENGTH PIC S9(4) COMP.
05 INPUT-VALUE PIC X(26).
COPY JNI.
* Parse input
UNSTRING INPUT-VALUE DELIMITED BY ALL " "
INTO LOAN-AMOUNT-IN INTEREST-IN NO-OF-PERIODS-IN.
* Convert to numeric values
COMPUTE LOAN-AMOUNT = FUNCTION NUMVAL(LOAN-AMOUNT-IN).
COMPUTE INTEREST = FUNCTION NUMVAL(INTEREST-IN).
COMPUTE NO-OF-PERIODS = FUNCTION NUMVAL(NO-OF-PERIODS-IN).
* Calculate annuity amount required
COMPUTE PAYMENT = LOAN-AMOUNT *
FUNCTION ANNUITY((INTEREST / 12 ) NO-OF-PERIODS).
* Format then display payment
MOVE PAYMENT TO PAYMENT-OUT.
DISPLAY 'Payment ' PAYMENT-OUT.
MOVE PAYMENT-OUT TO PAYMENT-SQL.
GOBACK.
4. Paste the COBOL code into the editor and save it (Figure 3-49).
3.4.2 Generating the JCL to compile, link, bind, and run COBLOAN
RDz can be used to generate JCL files with some customization to the RDz PROCs. This
allows you to specify information such as the data sets and compiler options. Each site has its
own configurations.
Example 3-7 provides the JCL we used to run the z/OS Batch Runtime, and add the
members COMPLINK and BCDRUN, using the steps described in “Adding COBLOAN” on
page 41.
3.4.3 Creating the Java launcher and copying the JNI copybook
The JNI copybook contains sample COBOL data definitions that correspond to the Java JNI
types. It also contains the JNINativeInterface and the JNI container structure that contains
function pointers for accessing the JNI callable services.
The JNI.cpy file is located in the subdirectory of the COBOL install directory, typically
/usr/lpp/cobol/include.
You can use RDz to copy an HFS file to a MVS partitioned data set (Figure 3-50).
The JZOS Launcher for V6.0.1(JVMLDM61) is located in the mvstools subdirectory of the
JVM install, typically /usr/lpp/java/J6.0.1/mvstools/.
import java.text.SimpleDateFormat;
import java.util.Calendar;
document.close();
System.out.println("PDF generated.");
4. The PdfCreator.class should appear under the src folder (Figure 3-54).
5. The JAVAC job will appear under the My Jobs filter under the JES node in the Remote
Systems view (Figure 3-55). Refresh this filter until the job completes.
2. As outlined in “Viewing application and container output” on page 8, all output from the
JVM (messages prefixed with JVM) and COBLOAN (no message codes) appears in
SYSOUT. The DISPLAY calls from COBLOAN are highlighted in Example 3-11. The
output shows that the calculations record was successfully inserted into the QUERIES
table.
5. The System.out output from PdfCreator appears in STDOUT. From the output
(Example 3-12) it appears that the PDF file was created and the QUERIES record
(inserted in COBLOAN) was updated to include the path of the PDF file.
The BCDOUT outputs z/OS Batch Runtime messages. The BCD0412I message is key
because it counts the number of transactions that were issued, committed, and rolled back.
Demonstrating a rollback
The COBLOAN INSERT and PdfCreator UPDATE database changes are defined as a single
transaction by the UserControlledTransactionHelper.commit() call at the end of PdfCreator.
PdfCreator is only called when the COBLOAN INSERT is successful. If any exceptions occur
in PdfCreator, then the INSERT from COBLOAN is discarded. One possible cause of an
exception in PdfCreator is if the statements folder cannot be found.
Example 3-14 demonstrates how this rollback changes the input values in BCDIN.
4. Submit the BCDRUN JCL. See Example 3-15 for the output in STDOUT. The STDOUT
output from this execution also suggests that it did not complete compared to the
STDOUT output from the previous execution shown in see Example 3-12 on page 54.
6. The z/OS Batch Runtime output in BCDOUT shows that one change was committed and
then rolled back (Example 3-17).
9. SYSOUT in the z/OS Batch Runtime returned a return code of 0 (Example 3-18).
However, this is not a true reflection of the execution of COBLOAN. A proposed solution is
outlined in the next section, 3.4.7, “Solution to reflect an exception in the return code”.
3. Modify COBLOAN to accept a return code from PdfCreator and MOVE that value to the
RETURN-CODE register (Example 3-21).
GOBACK.
4. Recompile COBLOAN via JCL COMPLINK and PdfCreator via JCL JAVAC. Submit
BCDRUN when all the applications have been recompiled successfully. You should see a
return code of 12 as shown in Example 3-22.
5. The JCL for the z/OS Batch Runtime BATCH step returns a return code of 8
(Example 3-23). As described in “Handling return codes and Java exceptions” on page 9 it
indicates that the primary application, COBLOAN, returned a return code greater than 0.
To reproduce this development scenario without having to copy/paste the source code listed
in this chapter, you can be download the necessary files from the Internet as described in
Appendix A., “Additional material” on page 63.
Select the Additional materials and open the directory that corresponds with the IBM
Redbooks form number, SG248116.
The publications listed in this section are considered particularly suitable for a more detailed
discussion of the topics covered in this book.
You can search for, view, download, or order these documents and other Redbooks,
Redpapers, Web Docs, draft and additional materials, at the following website:
ibm.com/redbooks
Other publications
These publications are also relevant as further information sources:
z/OS Batch Runtime: Planning and User’s Guide, SA23-7270
IBM DB2 Universal Database Application Development Guide: Programming Client
Applications, SC09-4826
Online resources
z/OS Java Technology Edition
http://www-03.ibm.com/systems/z/os/zos/tools/java/products/sdk601_31.html