Getting started
In this chapter, we help you get started with Java programming in a CICS environment using the latest IBM software development platform on system z, Rational Developer for System z.
We show you how to create the Java code in Rational Developer for System z and how to deploy the code to the mainframe and run it under CICS.
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;
}
/**
* 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)
}
}
•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 task owns 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 a PrintWriter 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
 
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.
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 location.
Example 4-2 Sample FTP session to copy dfjcics.jar to the development workstation
C:Documents and SettingsTOT195>cd C:Documents and SettingsTOT195IBM ationa
lsdp6.0workspaceSG24-5275
C:Documents and SettingsTOT195IBM ationalsdp6.0workspaceSG24-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 SettingsTOT195IBM ationalsdp6.0workspaceSG24-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.
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.
 
Note: If Rational Developer for System z did not rebuild your project after you changed the build path, select Window ∅ Preferences, select the Workbench category, and make sure that Build is checked.
4.2 Deploying and running the program
Now that the code is ready in Rational Developer for System z, the next step is to deploy it to the mainframe, and run it in CICS.
4.2.1 Deploying the code to CICS
You have many choices to move the bytecode to the mainframe. But if you are lucky enough to have Rational Developer for System z installed and configured properly on the mainframe, the deployment is easy and straightforward. We also include steps for the more generic way to use FTP as an alternative.
Exporting using Rational Developer for System z
Before you export the class file, we must make sure that Rational Developer for System z treats the class file as binary files, which means that no conversion is performed during the transfer:
1. Select the Preference menu, look for Remote Systems ∅ Files in the navigator, and click Add to add a file type “.class”.
2. Select File Transfer Mode to Binary. Click OK to apply the changes, and close the dialog.
Figure 4-4 Tell Rational Developer for System z to treat class file as binary
Now we can export class files to the mainframe UNIX System Services directory:
1. Select Export in the context menu of the project, select Other ∅ Remote file system, and select Next.
2. In the next page of the wizard, select only the classes directory in the project root, and then click Browse to select the target directory on your remote system (This directory should be a part of your classpath in the JVM profile used by the CICS region), also select Create directory structure for files.
3. Make sure everything looks good, and then click Finish. Now your Java class file is on its way to the mainframe.
Exporting using FTP
If your installation does not offer Rational Developer for System z access to the zFS file system, you can use FTP to export your code. Fortunately, you do not have to do this manually; Rational Developer for System z comes with built-in FTP support.
To export the code:
1. Select the project, and then in the context menu, select Export.
2. From the list of export destinations, select Other ∅ FTP, and click Next.
3. Click Browse, and select the classes directory to upload.
4. In the FTP host field, type the TCP/IP host name of your z/OS machine.
5. In the FTP folder field, type the name of the target zFS directory,  in our example, /u/cicsrs6/ (see Figure 4-5). Click Next.
6. Enter your user name and password. Click Finish.
Figure 4-5 Export to an FTP server wizard
 
Note: Unfortunately, the FTP export does not allow you to do ASCII-to-EBCDIC translation — it always transfers files in binary, which is OK for the .class files, but not if you want to ship the source code to the mainframe.
4.2.2 Setting up the transaction and program definitions
Next, we must set up the CICS transaction and program definitions for our program. We assume that all JVM-related set up, such as creating a JVM profile, is already complete. Also, we assume that a transaction and program definition are created for you to use, and that you are authorized to view and change the program definition attributes.
In the following discussion, we use transaction id HELO and program name HELOWRLD for our example. Depending on your installation standards, your friendly CICS system programmer might have set up different names.
1. First, we verify that the transaction’s initial program is set up to be HELOWRLD. Clear the CICS panel, and type CEMT INQUIRE TRANSACTION(HELO). CICS shows a panel that shows a summary of the HELO transaction’s attributes:
  INQUIRE TRANSACTION(HELO)
STATUS: RESULTS - OVERTYPE TO MODIFY
Tra(HELO) Pri( 001 ) Pro(HELOWRLD) Tcl( DFHTCL00 ) Ena Sta
Prf(DFHCICST) Uda Bel Iso Bac Wai
Thus, we verified that the transaction’s initial program is indeed HELOWRLD.
2. Next, we look at the definition of program HELOWRLD.
INQUIRE PROGRAM (HELOWRLD)
 STATUS: RESULTS - OVERTYPE TO MODIFY
Prog(HELOWRLD) Jav Pro Ena Ced
Res(001) Bel Uex Ful Thr Jvm
3. Expand the display by tabbing to the first line of the summary, and press Enter. Your display should look similar to Figure 4-6; however, we left out several attributes that are not relevant to this discussion.
INQUIRE PROGRAM (HELOWRLD)
RESULT - OVERTYPE TO MODIFY
Program(HELOWRLD)
Language(Java)
Progtype(Program)
Status( Enabled )
Copystatus( Notrequired )
Cedfstatus( Cedf )
Dynamstatus(Notdynamic)
Rescount(001)
Usecount()
Execkey(Uexeckey)
Executionset( Fullapi )
Concurrency(Threadsafe)
Remotesystem()
Runtime( Jvm )
Jvmclass( com.ibm.itso.sg245275.HelloWorld )
Jvmprofile( DFHJVMUG )
Figure 4-6 Program definition attributes
4. Verify that the Runtime attribute is set to Jvm and that the Jvmclass attribute is set to the Java class name of the program. If this is not the case, you can overtype the previous values, and press Enter to apply the changes. Also, verify that the JVM profile name is correct.
4.2.3 Running the program
Now, we are finally ready to run our program:
1. Clear the CICS panel, and enter the transaction code, as shown in Figure 4-7.
Figure 4-7 Output from the HELO transaction
If this did not run error free, refer to 4.2.4, “Troubleshooting” on page 74. If not, congratulations, you successfully ran your first program in the CICS Transaction Server.
2. Next, invoke the transaction in a way such that it is not associated with a terminal (in CICS terms, it does not have a principal facility). If the program works correctly, output goes to a zFS file instead. To do this, we use the CICS-supplied CECI transaction.
3. You can use the command-level interpreter (CECI) transaction to check the syntax of CICS commands and to process these commands interactively on a 3270 panel. Using CECI, you can follow through most of the commands to execution and display the results.
 
Tip: For a full description of CECI, refer to CICS Supplied Transactions, SC34-6230.
In 6.12, “Interval control” on page 124, we discuss Interval control services, which allows one transaction to asynchronously start another transaction. We now do that manually, using CECI, to start our Hello program:
1. On the CICS panel, type CECI, and press Enter. You get a list of all CICS commands, as shown in Figure 4-8.
STATUS: ENTER ONE OF THE FOLLOWING
ABend DELAy FREE POP RETRieve SUspend
ACquire DELETE FREEMain POSt RETUrn SYncpoint
ADD DELETEQ GDs PURge REWInd TEst
ADDRess DEQ GET PUSh REWRite TRace
ALlocate DISAble GETMain PUT ROute UNlock
ASKtime DISCard GETNext Query RUn UPdate
ASSign DOcument Handle READ SENd Verify
BIf DUmp IGnore READNext SET WAIT
BUild ENAble INquire READPrev SIGNOFf WAITCics
CAncel ENDBR ISsue READQ SIGNON WEb
CHAnge ENDBROwse Journal RECeive SPOOLClose WRITE
CHEck ENQ LInk RELease SPOOLOpen WRITEQ
COLlect ENTer LOad REMove SPOOLRead Xctl
CONNect EXtract MONitor RESET SPOOLWrite
CONVerse FEpi MOVe RESETBr START
CReate FORCe PErform RESUme STARTBR
DEFine FORMattime POInt RESYnc STARTBROwse
PF 1 HELP 2 HEX 3 END 4 EIB 5 VAR 6 USER 9 MSG
Figure 4-8 CECI transaction: Initial panel
2. We want to use the START command, which starts another transaction. Type START TR(HELO), and press Enter. CECI checks the command syntax, and because it is valid, responds with the message ABOUT TO EXECUTE COMMAND.
3. Press Enter again to actually execute the command. CECI responds with COMMAND EXECUTION COMPLETE.
This way of invocation causes the transaction to be run without a terminal being associated with it; therefore, the output from our program goes to a zFS file. The name and location of that zFS file are configured in the JVM profile under which the program was set up to run.
Example 4-3 on page 74 shows the zFS file from our example.
Example 4-3 zFS file /u/cicsvr6/work/A6POC3C4/dfhjvmout in our example
Hello CICSUSER, welcome to CICS!
 
This is program HELOPROG
Transaction name is HELO
CICS region is C3C4
Next, you can experiment with the debugging techniques that we explain in Chapter 8, “Problem determination and debugging” on page 193, for example, you might want to try the execution diagnostic facility (CEDF), or you can run the program under the control of the debugger to see what is going on.
4.2.4 Troubleshooting
If the program failed to run for whatever reason, a message similar to the following is displayed on the bottom of the CICS panel:
DFHAC2206 20:56:01 SCSCPJA7 Transaction HELO failed with abend AJ07. Updates
 to local recoverable resources backed out.
The most important piece of information is the abend code, which indicates what went wrong. (The abend code in itself is not exactly self-explanatory, but you can get an idea of what went wrong.)
 
Tip: See CICS Messages and Codes, GC34-6241, for a detailed explanation of each transaction abend code.
In fact, abend code AJ04 is one that you might see quite often. It means that the class that contains the main method of your application was not found, probably because your classpath is set up incorrectly or you misspelled the main class name on the program, see definition. Review 8.2.1, “Abend AJ04” on page 196, for more on this code.
Another common abend code is AJ05, which means that CICS code caught an unhandled exception, that is, an exception was thrown but never caught by your application, all the way up and beyond your application’s main method.
See Chapter 8, “Problem determination and debugging” on page 193, for more information about problem determination.
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset