Chapter 4. Getting started
4.1 Coding your application in Rational Developer for System z
Let us get started creating our first JCICS application. Traditionally, the first program to write and run in a new environment prints something like Hello World!, and the example presented in this chapter is no exception. To code your application in Rational Developer for System z: 1. Start Rational Developer for System z, and create a new Java project by selecting File∅
New∅ Project, and then select Java Project. Click Next, and enter the project name
SG245275. Click Finish.
2. Create a Java package called com.ibm.itso.sg245275 by selecting File∅ New∅ Package, and then create a new Java class called HelloWorld.
3. We show the source code for our Hello World in Example 4-1. It is a bit longer than usual for a first-time example, but it demonstrates a lot of useful things. Copy the program code from the PDF file (or the zip file available from the Redbooks Web site), and paste it into Rational Developer for System z. You will get tons of compilation errors, but we will fix these errors in the next step.
Example 4-1 Hello World!
package com.ibm.itso.sg245275; import java.io.PrintWriter; import com.ibm.cics.server.*; public class HelloWorld {
public static void main(CommAreaHolder cah) { // (1) try {
PrintWriter out = getOutputWriter(); // (2)
Task task = Task.getTask(); // (3)
out.println();
out.println("Hello " + task.getUSERID() + ", welcome to CICS!"); // (4) out.println();
out.println("This is program " + task.getProgramName()); // (5) out.println("Transaction name is " + task.getTransactionName()); // (6) out.println("CICS region is " + Region.getSYSID()); // (7) } catch (Throwable e) {
System.err.printStackTrace(); // (8) }
}
/**
* Return the terminal principal facility, or <code>null</code> * if the transaction is not associated with a terminal. */
private static TerminalPrincipalFacility getTerminal() {
Object principalFacility = Task.getTask().getPrincipalFacility(); // (9) if (principalFacility instanceof TerminalPrincipalFacility)
return (TerminalPrincipalFacility) principalFacility; // (10) else
return null; // (11)
}
/** Is the transaction associated with a terminal? */
private static boolean haveTerminal() { // (12) return getTerminal() != null;
}
Chapter 4. Getting started 65
* Return a PrintWriter that is either directed at the terminal, if * we have one, or to <code>System.out</code> if not.
*/
private static PrintWriter getOutputWriter() { if (haveTerminal())
return Task.getTask().out; // (13) else
return new PrintWriter(System.out, true); // (14) }
}
Notes on Example 4-1 on page 64:
The first thing to notice is that, unlike “regular” standalone Java applications, the main() method in CICS Java programs takes an argument of type CommAreaHolder, instead of the familiar String[]. A main method with a string array argument is supported as well, but if both are present, CICS calls the one with the CommAreaHolder argument. We talk about Commareas in Calling other programs and passing data.
Get an output writer to print to. Depending on the environment, output either goes to the terminal if we have one; otherwise, it goes to a zFS file. However in CICS Transaction Server 3.2, you can get the task PrintWriter to associate the related terminal or
System.out by using Task.getTask().out directly to make life easier. The reason we keep the getOutputWriter() implementation is to give you a chance to have a better
understanding the JCICS API better.
Get a singleton instance of class Task, which has methods to inquire about information about our environment, such as the:
– User ID that is signed on – Program name
– Transaction code under which we are running
Print the system ID of our CICS region.
Any uncaught exceptions are caught here, and a stack trace is printed on System.err. Note that we could have decided to only catch checked exceptions; if an unchecked exception (such as NullPointerException) occurred, launcher code in CICS catches it, which in turn causes the task to abnormally end (abend).
Get the
principal facility
associated with the task. CICS assigns the principal facility when it initiates the task, and the taskowns
the facility for its duration. No other task can use that terminal until the owning task ends. Not all tasks have a principal facility. If we do have one, it is an instance of TerminalPrincipalFacility.
If we do not have a terminal, return
null
. Return
true
if we have a terminal. If we have a terminal, return a
PrintWriter
whose output goes to the terminal; otherwise, return aPrintWriter
whose output goes to System.out. This stream is associated with a file on the zFS file system. The boolean parameter to the PrintWriter constructor call causes the println() methods to flush the output buffer.As we said before, you will get a lot of compilation errors because the Jar file implementing the JCICS API (dfjcics.jar) is missing from the project. Because it does not come with the Rational Developer for System z product, we must get a copy from the mainframe:
1. Connect to the remote mainframe system in the Remote Systems view in the z/OS Project Perspective, and expand the UNIX System Services Files.
2. Navigate to your CICS installation directory. the dfjcics.jar file is in the lib sub-directory. Right-click, and select Copy.
3. Navigate to the project root directory in Local Files, right-click, and select Paste to download a copy to the local hard disk, as shown in Figure 4-1.
4. Switch back to the Java perspective, right-click the project, select Refresh. Now the dfjcics.jar is there.
Figure 4-1 Download dfjcics.jar to the local project on the workstation
As an alternative, you can also use the traditional way to download dfjcics.jar using FTP into your project directory if the mainframe is not set up for Rational Developer for System z yet. We list a sample FTP session in Example 4-2 on page 67 that assumes that the Rational Developer for System z workspace and the CICS library files are at their installation-default
Tip: If you do not know the location in the file system of the Rational Developer for System
z workspace, and therefore our project root folder, (the path name tends to be rather long), there is an easy way to find out:
1. Right-click the project, and select Properties.
2. In the dialog that opens, select the Info category. The project root folder name appears in the dialog box, and you can copy it from there, and paste it into the command prompt window.
Chapter 4. Getting started 67
Example 4-2 Sample FTP session to copy dfjcics.jar to the development workstation
C:\Documents and Settings\TOT195>cd C:\Documents and Settings\TOT195\IBM\rationa
lsdp6.0\workspace\SG24-5275
C:\Documents and Settings\TOT195\IBM\rationalsdp6.0\workspace\SG24-5275>ftp wtsc
66.itso.ibm.com
Connected to wtsc66.itso.ibm.com.
220-FTPMVS1 IBM FTP CS V1R6 at wtsc66.itso.ibm.com, 23:36:52 on 2005-04-05. 220 Connection will close if idle for more than 5 minutes.
User (wtsc66.itso.ibm.com:(none)): cicsrs3 331 Send password please.
Password: ********
230 CICSRS3 is logged on. Working directory is "CICSRS3.". ftp> cd /usr/lpp/cicsts/cicsts32/lib
250 HFS directory /usr/lpp/cicsts/cicsts32/lib is the current working directory ftp> bin
200 Representation type is Image ftp> get dfjcics.jar
200 Port request OK.
125 Sending data set /usr/lpp/cicsts/cicsts32/lib/dfjcics.jar 250 Transfer completed successfully.
ftp: 139283 bytes received in 0.02Seconds 6964.15Kbytes/sec. ftp> quit
221 Quit command received. Goodbye.
C:\Documents and Settings\TOT195\IBM\rationalsdp6.0\workspace\SG24-5275>
Now that dfjcics.jar is copied to our project directory, we must tell Rational Developer for System z to include it on the compiler class path:
1. Right-click the project name, and select Properties. Switch to the Java Build Path category, and click Add Jars, as shown in Figure 4-2 on page 68.
Figure 4-2 Setting up the Java build path in Rational Developer for System z
2. In the dialog that opens, expand the project folder, select dfjcics.jar, and then click OK. The “JARs and class folders on the build path” list box should now include dfjcics.jar. Click
OK again to finish the build path setup.
3. Switch to the Source tab in the project properties dialog, select the Browse button beside the Default output folder field, and create a new folder named “classes”. Click OK, and it will look something like Figure 4-3 on page 69.
Chapter 4. Getting started 69
Figure 4-3 Select separate directory for output files.
By doing this, we change the default output directory that contains bytecodes to the classes directory in the project root, which is deployed onto the mainframe later. Click OK to close the project properties dialog.
Because the build path changed, Rational Developer for System z rebuilds your project. The compilation errors should be gone because all required libraries are included. In the next step, we deploy the code to the mainframe, and run it in CICS.