| Sun Mainframe Transaction Processing Software Developer's Guide |    
|
| Sun Mainframe Transaction Processing Software Developer's Guide |
|
| C H A P T E R 8 |
|
Using Java Programs |
The Sun MTP software provides the ability to run online and batch applications that are written in the Java programming language. This chapter focuses on the use of Java programs in the online environment. To use Java programs in the Sun Mainframe Batch Manager (Sun MBM) environment, refer to the Sun Mainframe Batch Manager Software Migration Guide.
This chapter contains the following topics:
To use the Java CICS API (JCICS), your system must be running at least the Solaris 2.8 operating environment. You must also:
).
is located in the $JDKROOT/jre/lib/sparc directory.
|
Note - $JDKROOT is used to identify the installation directory of the Java Development Kit. |
Unlike other programming languages supported in the Sun MTP environment, Java programs do not use the EXEC CICS API. A Sun MTP application written in the Java programming language uses the JCICS API instead.
IBM introduced the JCICS API into its CICS Transaction Server version 1.3 for the OS/390 product. Details of the JCICS API are in the IBM Redbook Java Application Development for CICS, part number SG24-5275-01, which is available online.
The JCICS API is not a translated EXEC CICS API as the C and COBOL language APIs are. Rather, it consists of a set of Java classes invoked from a Java Sun MTP application in the same manner as any other set of Java classes. Full documentation of the subset of the JCICS APIs currently supported by Sun MTP is available as Javadoc format HTML in the directory $UNIKIX/doc/jcics.
Although the full JCICS API is available to the programmer (that is, the relevant classes and methods exist), there are significant areas that are not yet fully implemented. When an API call is made to an unimplemented method, a com.sun.emp.mtp.jcics.NotImplementedException is raised. The Javadoc for the JCICS API indicates the methods to which this applies.
In this release of JCICS for Sun MTP, support is provided for the majority of the program control sections of the JCICS API, as well as selected sections of task control and terminal control. Minor pieces of other parts of the API are also implemented.
A JCICS program is defined to Sun MTP in the same way as a program written in any other language. The program requires a PPT definition, and if the program is to be invoked as the first program in a transaction, you must add a PCT entry.
A JCICS program can also be called from any other Sun MTP program, including those written in a different language such as COBOL, by using EXEC CICS LINK. A JCICS program can perform such links to any other Sun MTP program. With the JCICS API, this is achieved using the method link() in the program class.
When a JCICS program is invoked, control is passed to the user's Java application in one of two places. Normally, the specified Java class has a static main() method defined, which takes a CommareaHolder as a parameter. This method is defined as:
public static void main(CommareaHolder cah);
If this method does not exist, then a method defined as:
public static void main(String[] array);
will be invoked. If neither of these methods exist, the program invocation fails.
The following example shows a JCICS program that displays the string Hello World on the user's terminal if run as part of a terminal-attached transaction.
The Task class is key to writing a JCICS application. An application can obtain access to a Java printwriter called out from the Task class. For a terminal-attached transaction, any data written to this printwriter will be displayed on the user's terminal.
|
Note - The JCICS classes supplied by Sun MTP are provided in Java packages whose names begin com.ibm. This aids portability of JCICS programs from IBM Transaction Server to Sun MTP. |
JCICS applications are built in exactly the same manner as any other Java programs. The javac command is used to compile the required classes. With JCICS programs, some of the classes written for your application will contain references to classes provided by Sun MTP. These classes are located in the $UNIKIX/lib/dfjcics.jar file. Therefore, to compile the JCICS application classes, you must specify these classes on the compiler's classpath. You can either set the CLASSPATH environment variable, or specify the -classpath option on the javac command. The following command shows how to specify the -classpath option on the javac command.
The compiled program is HelloWorld.class.
If you are using an Integrated Development Environment (IDE) such as IBM's VisualAge for Java to compile your programs, or are using third party products, refer to your user documentation to determine how to make these classes available to your compiler.
The JCICS framework uses the Sun MTP environment variable KIXPROGS to set the classpath attribute to the JVM. To instruct the JCICS classloader to load additional class or JAR files, you can use the Classpath.appends and Libpath.appends files.
|
1. Shut down the region if it is running.
2. Make sure your region environment is set.
3. Change to the region's $KIXSYS directory and create the kix_java directory.
4. Change to the kix_java directory.
5. Copy the Classpath.appends and Libpath.appends files from the $UNIKIX/lib/kix_java directory.
6. Add any entries you require to these files and save them.
You must define a JCICS program to Sun MTP in the PPT in the same way as any other program, such as one written in COBOL or C.
|
1. Start the region and make a client connection.
2. Enter the CTBL transaction to open the Table Manager.
3. Press PF4 to display the Standard Tables menu.
5. Press PF4 to insert a new entry.
6. On the PPT insert screen, make the following entries:
a. In the Program field, type the name of the program; for example HELLOW2.
b. In the Typ field, type J (indicating a Java program).
See FIGURE 8-1.
8. Press PF3 to return to the main PPT screen.
9. On the main PPT screen, select the HELLOW2 program and press PF9 to open the Java Class Details screen.
10. On the Java Class Details screen, type the Java class name in the Fully qualified JAVA Class Name field. Do not include the class suffix or an error occurs at runtime.
The name in the Program field is the program you selected on the PPT main screen.
The Remote Object and IIOP Connectivity fields are not used in this release.
11. Press Enter to add this information.
12. Press PF3 to return to the main PPT screen.
13. On the main PPT screen, press PF2 to write the table changes to disk.
14. Press PF3 twice to return to the Table Manager main menu.
15. Press PF3 to exit Table Manager.
In this example, the fully qualified name of the Java class to be invoked when the JHELLOW2 program is run is called HelloWorld. If the class is part of a Java package, then that package name must be specified as part of this entry.
Place the class file for the JCICS program in the region's $KIXPROGS directory so that Sun MTP can locate and execute it. In Sun MTP, the contents of $KIXPROGS is passed to the JVM as its CLASSPATH. For example, the class file for a JCICS program defined as HelloWorld in the Java Class Details screen of the PPT must be accessible to the region as $KIXPROGS/HelloWorld.class.
You can also package your application class files in an archive file, such as a Java archive or zip file. If you do, include the path and file name of the archive file(s) in $KIXPROGS, as shown in a region setup file:
|
Note - $KIXPROGS can be a colon-separated list of directories. |
Some special configuration is required to start a region that can execute JCICS programs.
If you intend to run Sun MTP programs that are written in COBOL as well as Java programs, you must use Server Express 2.2.
|
1. Install the Java JDK (minimum release JDK 1.4).
2. Set the LD_LIBRARY_PATH environment variable.
The directories $JDKROOT/jre/lib/sparc and $UNIKIX/bin are required as part of LD_LIBRARY_PATH to enable Java support. The $COBDIR/lib directory is set in the following example because it is typically required for a region running Server Express. The export LD_LIBRARY_PATH statement must be on one line. For example, in the region setup file:
3. Add JVM options if you are debugging application programs.
4. Start your region in the normal way.
When your region has started successfully with Java support, the following message is written to the unikixmain.log file for each transaction processor the region starts:
Each Sun MTP transaction processor starts and owns its own in-process JVM in order to execute user-written JCICS code. You can modify the behavior of this JVM by setting the environment variable KIX_JVM_OPTIONS.
Set KIX_JVM_OPTIONS to include any JVM startup flags that would normally be given to a standalone JVM as command-line parameters to the java executable. To see which flags the java executable accepts, you can run the command java -?.
For example, to start the JVMs owned by the transaction processors with verbose debugging information for garbage collection, set KIX_JVM_OPTIONS as follows before starting the region:
It is not permitted to set the classpath or library path used by the JVM. For example, you cannot specify -Djava.class.path=... or -Djava.library.path=....
This section describes restrictions and limitations when executing JCICS programs in Sun MTP.
Each transaction that runs under control of Sun MTP runs within a single transaction processor process. Each transaction processor is also capable of running a JVM in order to execute JCICS programs that are required by a transaction.
In this multi-process model, any Java static data set during the execution of a user-written JCICS class might not be available with that value to a subsequent transaction that uses that class. This is because it might be executing in a different transaction processor and therefore running a different JVM.
To store data persistently, use the standard Sun MTP facilities, for example, temporary storage queues or transient data queues.
The Java programming environment is inherently multi-threaded. However, additional restrictions are placed upon a Java (JCICS) program running under the control of Sun MTP.
Primarily, calls to the JCICS API can only be made from the main thread; that is, the thread upon which the main() method of the JCICS program was invoked.
| Sun Mainframe Transaction Processing Software Developer's Guide | 816-5329-11 |
|
Copyright © 2004, Sun Microsystems, Inc. All rights reserved.
To Make the Classpath.appends and Libpath.appends Files Available