In addition to the substantial integration with Qshell that the Java runtime provides, application development can be done in Java directly from a Qshell environment.

Three Java command-line utilities stand out above all the others in terms of importance: the java utility, the javac utility, and the jar utility.

The Java Utility

Java developers on iSeries can provide Java applications with CL command interfaces, Qshell command interfaces, or other server-side, command-line user interfaces. Java applications range from simple stand-alone applications to large and complex applications that run within a Java server environment like Websphere Application Server.

You use the java utility to run stand-alone Java applications. The utility creates a Java runtime environment (including the Qshell terminal), loads a Java application, and runs it.

Here are two versions of the java syntax that start the execution of a Java class:

java [options] class-name [parameters] java -jar [options] jar-file-name [parameters] file

Java Options

Depending on the version of the java command that you use, different option parameters are available. Table 23.1 shows the more commonly used options.

Running Java

To run the java utility, the Java executable code (classes) and the CLASSPATH environment variable need to be set up correctly. Setting CLASSPATH correctly requires an understanding of some of the fundamentals of Java application-development and packaging. You must know the packaging of the applications and third-party libraries you are using. A frequent problem when doing Java development involves difficulties with setting the CLASSPATH variable (or parameter) correctly.

Java Files

A Java class defines one of the most basic units of application development in a Java program. Most commonly, a single Java compilation unit (an ASCII .java file) defines a single java class. After compilation, the class is contained within a .class file. The .class file is the binary representation of the Java class consisting of Java byte-code instructions. The class file is binary, and is compatible with existing Java implementations on any platform.

The Java language also supports units of application development other than the class, and allows more than one of these structures in a single file. For further reading, study Java interfaces, abstract classes, inner classes, and private or protected classes. A good place to start might be the book Thinking in Java by Bruce Eckel. The electronic form of this book is available for free at www.bruceeckel.com. Another alternative might be a book The Java Tutorial by Mary Campione, also available for free, at www.thejavatutorial.com.

As a beginner, put one Java class in each ASCII .java file. Create Java applications using one or more of those java classes. The classes might or might not access third-party library code. Each class definition includes a statement describing the package that contains the class.

Java Packages

The Java package name serves multiple purposes. The package fully qualifies a class name, allowing it to be uniquely distinguished from other classes. The package also identifies and groups one or more Java classes. Java classes inside a package have privileged access to some of the internals of other Java classes in the same package. The package also describes the physical packaging structure of the Java class.

Use a package and put your .java files and the resulting .class files in a directory structure matching the package name. When you refer to the package or the fully qualified class name, use the Java notation for the package name, with dots separating the elements. When you refer to the file or directory name, use Qshell notation for the package name, with slashes separating the elements.

You can deliver Java applications and classes as stand-alone files, or as part of a jar or zip file. (Jar files are created with the jar utility, discussed later in this chapter.) The classes in the jar or zip file must be contained within a directory entry in the archive file that matches the package name.

Java class files and archive files are binary files, so you cannot modify them with an editor. Similarly, you cannot successfully upload or download them with an ASCII-mode file transfer (in FTP, for example).

Java System Properties

Use the -D option to set Java system properties that control the behavior of the Java runtime environment. Each Java application usually has a unique set of Java system properties that it uses to control its behavior.

The iSeries JVM (Java Virtual Machine) uses Java system properties to affect its internal behavior. Table 23.2 describes some of the more commonly used system properties.

Use this property to modify the behavior of Runtime.exec().

The Javac Utility

The javac utility compiles Java source code contained in an ASCII file into a Java executable, composed of binary class files. The resulting binary class files can be used on any Java platform; transfer them in binary mode to the target system.

When the javac command compiles source files, it uses the current CLASSPATH setting to find classes that the source files are dependent on. The javac utility provides a limited dependency-checking capability to assist in building Java projects. If javac finds source files for dependent classes before it finds the class files, it compiles the source files to get the dependent classes. Similarly, if javac finds both the source files and the class files for the dependent classes, but the class files are older than the source files, the source files for the dependent classes are recompiled.

The syntax of the javac command to compile Java source code is as follows :

javac [options] ...

Depending on the version of the javac command that you use, different option parameters are available. Table 23.3 shows the more commonly used javac options.

The Javadoc Utility

The javadoc utility provides a standard mechanism by which a Java developer can provide API documentation for the classes that they develop. Delivering documentation is a critical step in developing classes and APIs in a team, department, or corporate environment. Other developers need to be able to understand the services provided.

In a hectic development environment, it is very easy for documentation and APIs to become hopelessly out of date in relation to each other. The Java language addresses this problem by combining source code and documentation in a simple and standard way. It defines the syntax of the source-code comments, and the tags used in those comments, to define detailed descriptions of the code.

The javadoc utility parses Java source code similar to the javac compiler. Instead of generating binary code from the source statements, however, the javadoc utility focuses on the Java comments. It looks at packages, class declarations, and method declarations, and is very tolerant of Java source code that does not compile.

The javadoc utility uses the comments and tags to generate HTML documentation describing the APIs. If run against a group of Java source files, the HTML documentation automatically generates a table of contents and an index. The group of files and the classes and methods contained within are automatically cross-referenced in a way that enables even the simplest documentation to become fairly professional and useful. However, the javadoc utility supports a varied and robust set of tags (in addition to HTML tags and links), so that a developer can generate as detailed and feature-rich a set of documentation as desired.

You can generate useful javadoc documentation without using any of the special javadoc tags that are inserted into those comments. Simply use the javadoc comment immediately preceding each class, variable, and method that you declare. Regular multiline Java comment start with /* and end with */. A javadoc comment starts with /** and ends with */.

The javadoc utility will even generate documentation for Java source with no comments. The generated documentation will still have the class, interface, method names , and types. The documentation will also have an index and cross-references generated in a very useful fashion.

Running the Javadoc Utility

The javadoc utility is a bit more flexible in the type of parameters it accepts than other Java utilities. Javadoc accepts Java package names, source file names, individual Java class names, or text files that contain lists of option parameters or Java package names.

Here is the syntax of the javadoc command to generate documentation from Java source code:

javadoc [options] [packages] [sourcefiles] [classnames] [@files]

Javadoc Options

Table 23.4 describes some of the basic javadoc options.

Javadoc Tags

Table 23.5 describes some of the more commonly used javadoc documentation tags.

A Javadoc Example

Figure 23.1 illustrates the javadoc utility. The documentation is output to the "doc" directory, and is then archived into a single file using the jar utility. The archive can be moved to a workstation or distributed as appropriate.

cat com/mcpress/qshell/JavaDocExample.java package com.mcpress.qshell; /** * This class represents a simple example for * using javadoc comments. The first line of * every javadoc comment is a summary of the class * or method, while the subsequent lines of the * comments are used for the detailed description * that the javadoc utility generates. * * @author Joe Smith * @version 1.0 */ public class JavaDocExample { /** * The internally maintained application name */ private String name = null; /** * The name of the database table used to lookup * the customer */ private String customerDatabase = null; /** * The getApplicationName() method returns the name * of the application. The name of the application * is generated randomly based on the time of * day. * * @return String representing the application name * @see com.mcpress.qshell.JavaDocExample#getName * @deprecated */ public String getApplicationName() { return null; } /** * The getName() method returns the true name of * the application. The name of the application is * the full name of the class containing the main * method. * * @return String representing the application name * @since 1.1 */ public String getName() { return null; } /** * The lookupCustomer() method looks up a customer * based on customer ID. The customer ID is the ID * that we print on all invoices and use in database * tables to uniquely identify a customer. * * @param number Unique customer ID * * @return The customer name or null if the * customer wasn't found */ public String lookupCustomer(int number) { } } mkdir doc ls com/mcpress/qshell/*.java com/mcpress/qshell/Args.java com/mcpress/qshell/CustomerDBLookup.java com/mcpress/qshell/CustomerList.java com/mcpress/qshell/CustomerLookup.java com/mcpress/qshell/HelloJava.java com/mcpress/qshell/JavaDocExample.java c om/mcpress/qshell/LineCounter.java com/mcpress/qshell/PtfStatus.java com/mcpress/qshell/Reverse.java javadoc -d doc -private -windowtitle "Qshell javadoc example" com/mcpress/qshell/*.java Loading source file com/mcpress/qshell/Args.java... Loading source file com/mcpress/qshell/CustomerDBLookup.java... Loading source file com/mcpress/qshell/CustomerList.java... Loading source file com/mcpress/qshell/CustomerLookup.java... Loading source file com/mcpress/qshell/HelloJava.java... Loading source file com/mcpress/qshell/JavaDocExample.java... Loading source file com/mcpress/qshell/LineCounter.java... Loading source file com/mcpress/qshell/PtfStatus.java... Loading source file com/mcpress/qshell/Reverse.java... Constructing Javadoc information... Building tree for all the packages and classes... Building index for all the packages and classes... Generating doc/overview-tree.html... Generating doc/index-all.html Generating doc/deprecated-list.html... Building index for all classes... Generating doc/allclasses-frame.html... Generating doc/index.html... Generating doc/packages.html... Generating doc/com/mcpress/qshell/Args.html... Generating doc/com/mcpress/qshell/CustomerDBLookup.html... Generating doc/com/mcpress/qshell/CustomerList.html... Generating doc/com/mcpress/qshell/CustomerLookup.html... Generating doc/com/mcpress/qshell/HelloJava.html... Generating doc/com/mcpress/qshell/JavaDocExample.html... Generating doc/com/mcpress/qshell/LineCounter.html... Generating doc/com/mcpress/qshell/PtfStatus.html... Generating doc/com/mcpress/qshell/Reverse.html... Generating doc/serialized-form.html... Generating doc/package-list... Generating doc/help-doc.html... Generating doc/stylesheet.css... ls doc allclasses-frame.html index-all.html packages.html com index.html serialized-form.html deprecated-list.html overview-tree.html stylesheet.css help-doc.html package-list jar cf doc.jar doc

Figure 23.1: This example demonstrates using the javadoc command on a group of classes.

The doc.jar file from Figure 23.1 is transferred to a client workstation and extracted. Figure 23.2 shows what the documentation looks like when a browser displays the doc/index.html file. Because the set of classes used in Figure 23.1 only defines one package, there is a table of contents for the individual classes, but not for the packages.

Figure 23.2: Javadoc documentation may be viewed with a Web browser.

The Jar Utility

The jar utility provides support for creating and extracting Java archives. A Java archive is a zip-format file that typically contains java class files, although a jar file may contain any file type. The Java archive also contains additional information ( meta-information ), added by the jar utility to describe the contents of the archive file and attributes of the Java classes or applications in the file. Use a jar file as part of the CLASSPATH to allow the java runtime access to the classes or other resources in the jar file.

The syntax of the jar utility, shown below, is unique compared to other Qshell utilities:

jar [options] <-C directory>

Note that the option parameters must be grouped together, and they do not require leading dashes (except for the - C parameter). The jar utility accepts option parameters ( m and f ) that require file names, but those file names are not specified immediately following the parameter. The utility recursively processes any directories named on the command line.

Table 23.6 shows values for the action option. At least one of the values in Table 23.6 must be specified.

Table 23.7 shows other options for the jar utility. If the f and m options are both used, specify the jar-file and manifest-file parameters in the same order as the options parameters.

In Figure 23.3, the jar utility is used to zip the java source and class files. The output is produced due to inclusion of the v option.

pwd /home/jsmith/src jar cvf sourceAndBinaries.jar com added manifest adding: com/(in = 0) (out= 0)(stored 0%) adding: com/mcpress/(in = 0) (out= 0)(stored 0%) adding: com/mcpress/qshell/(in = 0) (out= 0)(stored 0%) adding: com/mcpress/qshell/CustomerList.class(in = 2091) (out= 1173)(deflated 43%) adding: com/mcpress/qshell/CustomerList.java(in = 1710) (out= 587)(deflated 65%) adding: com/mcpress/qshell/CustomerLookup.class(in = 2791) (out= 1557)(deflated 44%) adding: com/mcpress/qshell/CustomerLookup.java(in = 3967) (out= 1214)(deflated 69%) adding: com/mcpress/qshell/HelloJava.class(in = 599) (out= 367) (deflated 38%) adding: com/mcpress/qshell/HelloJava.java(in = 197) (out= 144) (deflated 26%) adding: com/mcpress/qshell/CustomerDBLookup.class(in = 2879) (out= 1671)(deflated 41%) adding: com/mcpress/qshell/CustomerDBLookup.java(in = 4097) (out= 1350)(deflated 67%) adding: com/mcpress/qshell/PtfStatus.class(in = 2401) (out= 1333)(deflated 44%) adding: com/mcpress/qshell/PtfStatus.java(in = 3434) (out= 1062) (deflated 69%)

Figure 23.3: Use the jar utility from your base source-file directory to zip the java source and class files.

Jar files are compatible with the WinZip and PKZip utilities, so you can also use jar as a convenient command-line zip/unzip utility to manipulate zip archives, if no other archive tool is present. Using the M option, as in Figure 23.4, ensures that no manifest files are added to the archives. Adding the v option to the t option generates a listing that contains information about the files' sizes and dates.

jar cfM classes.jar com/mcpress/qshell/*.class jar tvf classes.jar 2879 Thu Jun 05 02:51:20 UTC 2003 com/mcpress/qshell/CustomerDBLookup.class 2091 Thu Jun 05 02:47:58 UTC 2003 com/mcpress/qshell/CustomerList.class 2791 Thu Jun 05 02:47:58 UTC 2003 com/mcpress/qshell/CustomerLookup.class 599 Thu Jun 05 02:47:58 UTC 2003 com/mcpress/qshell/HelloJava.class 2401 Fri Jun 06 05:36:52 UTC 2003 com/mcpress/qshell/PtfStatus.class

Figure 23.4: Use the jar utility to create and list the contents of an archive. The M option prevents a META-INF/MANIFEST.MF file from being created in the archive file.

Java Examples

Starting with a typical "Hello World" example and working up to more complex techniques, the code samples in this section show various ways that your Java application can interact with Qshell. The examples for phone-number lookup, PTF status, and database access are very similar to those coded in perl in chapter 22, and in C in chapter 24. These implementations of similar programs in three different languages provide you with a good basis for comparing perl, Java, and C.

The example in Figure 23.5 shows Java source code and an appropriate directory structure for Java application development. It demonstrates the javac utility and the java utility. The CLASSPATH environment variable is set to the base location of classes. The package name further qualifies the classes stored in that location by modifying both the full class name and the java/class file location. The Java application sets a Qshell exit status.

pwd /home/jsmith/src find /home/jsmith/src /home/jsmith/src /home/jsmith/src/com /home/jsmith/src/com/mcpress /home/jsmith/src/com/mcpress/qshell /home/jsmith/src/com/mcpress/qshell/HelloJava.java cat com/mcpress/qshell/HelloJava.java package com.mcpress.qshell; import java.lang.*; class HelloJava { public static void main(String args[]) { System.out.println("Hello Java"); System.exit(5); } } export CLASSPATH=/home/jsmith/src javac com/mcpress/qshell/HelloJava.java find /home/jsmith/src /home/jsmith/src /home/jsmith/src/com /home/jsmith/src/com/mcpress /home/jsmith/src/com/mcpress/qshell /home/jsmith/src/com/mcpress/qshell/HelloJava.class /home/jsmith/src/com/mcpress/qshell/HelloJava.java java com.mcpress.qshell.HelloJava Hello Java echo $? 5 unset CLASSPATH java -classpath /home/jsmith/src com.mcpress.qshell.HelloJava Hello Java

Figure 23.5: This example shows Java source code and an appropriate directory structure for Java application development.

Figure 23.6 demonstrates a customer list in Java. This example is used as a building block for the more complex examples that follow.

cat com/mcpress/qshell/CustomerList.java package com.mcpress.qshell; import java.util.Hashtable; public class CustomerList { public final static String NONE = "none"; Hashtable table; public CustomerList() { table = new Hashtable(); table.put("Chuck", "444-2345"); table.put("Bubba", "444-1111"); table.put("Billy Bob", "444-4340"); table.put("Amos", "333-1119"); table.put("Otis", "444-8000"); table.put("Claude", "333-4340"); table.put("Roscoe", "444-2234"); table.put("Arlis", "444-1314"); table.put("Junior", "BR-549"); table.put("Bill", "333-4444"); table.put("Ernest T.", NONE); } public String lookup (String name) { return (String)table.get(name); } public static void main(String args[]) { if (args.length == 0) { System.err.println("Usage: java CustomerList [name-to-lookup]"); System.exit(1); } CustomerList list = new CustomerList(); String item; for (int i=0; i item = list.lookup(args[i]); if (item == null) { System.err.println("Didn't find customer:" + args[i]); } else { if (item == NONE) { System.err.println("No listing for" + args[i]); } else { System.out.println("Found" + args[i] + "at" + item); } } } // end of for (i=0 < args.length) System.exit(0); } // end of main } export CLASSPATH=/home/jsmith/src javac com/mcpress/qshell/CustomerList.java java -cp /home/jsmith/src com.mcpress.qshell.CustomerList Chuck Bubba Found Chuck at 444-2345 Found Bubba at 444-1111

Figure 23.6: This example demonstrates a simple command-line lookup utility. This application has the data written directly into the Java application. Expanding this example to read in the data would produce a more flexible application.

Using the goodoleboys.txt data file (from Figure 21.1), Figure 23.7 demonstrates a functioning, interactive phone-number lookup application. This application uses two Hashtable objects to provide lookup services based on the data file. Compare and contrast this code with the similar perl example in chapter 22 (Figure 22.7) and the C example in chapter 24 (Figure 24.5).

pwd /home/jsmith/src cat com/mcpress/qshell/CustomerLookup.java package com.mcpress.qshell; import java.util.Hashtable; import java.io.*; public class CustomerLookup { public final static String NONE = "none"; // Two Hashtables mapping one object to another Hashtable numberByOleBoy = new Hashtable(); Hashtable oleBoyByWife = new Hashtable(); public CustomerLookup(String filename) throws IOException { // Use a LineNumberReader on top of a FileInputStream object. LineNumberReader in = new LineNumberReader( new InputStreamReader( new FileInputStream(filename) )); // Read each line and split into its components. String line = in.readLine(); while (line != null) { String oleBoy = line.substring(0,10); oleBoy = oleBoy.trim(); String oleBoysWife = line.substring(37, 47); oleBoysWife = oleBoysWife.trim(); String phoneNumber = line.substring(19, 27); phoneNumber = phoneNumber.trim(); if (phoneNumber.equals("none")) { phoneNumber = NONE; } numberByOleBoy.put(oleBoy, phoneNumber); oleBoyByWife.put(oleBoysWife, oleBoy); line = in.readLine(); } } /** * Lookup a phone number based on the name of the customer or * his wife. Return CustomerLookup.NONE if the customer has no * phone, Return the phone number string if found. Return null * if not found. */ public String lookup(String name) { String phoneNumber = (String)numberByOleBoy.get(name); if (phoneNumber == null) { String oleboy = (String)oleBoyByWife.get(name); if (oleboy != null) { phoneNumber = (String)numberByOleBoy.get(oleboy); } } return phoneNumber; } public static void main(String args[]) { if (args.length != 1) { System.err.println("Usage: java CustomerLookup data-file"); System.exit(1); } try { CustomerLookup list = new CustomerLookup(args[0]); String item; String name; // Get a 'nicer' interface over the System.in object // that represents standard input. We'll use LineNumberReader // just for fun. LineNumberReader in = new LineNumberReader(new InputStreamReader(System.in)); while (true) { System.out.println("Enter 'exit' or a name to lookup:"); // Read the next name from standard input, any input // class (API) that could be constructed from System.in // could be used here. name = in.readLine(); if (name == null) { // All done. break; } if (name.equals("exit") name.equals("quit")) { break; } // Lookup the name item = list.lookup(name); if (item == null) { System.err.println("Didn't find customer:" + name); } else { if (item == NONE) { System.err.println("No listing for" + name); } else { System.out.println("Found" + name + "at" + item); } } } // Exit successfully. System.exit(0); } catch (Exception e) { System.err.println("Error occurred"); e.printStackTrace(); // Exit in error condition. System.exit(2); } } // end of main } export CLASSPATH=/home/jsmith/src javac com/mcpress/qshell/CustomerLookup.java java com.mcpress.qshell.CustomerLookup /home/jsmith/src/goodoleboys.txt Enter 'exit' or a name to lookup: Bill Found Bill at 333-4444 Enter 'exit' or a name to lookup: Daisy Found Daisy at 333-4444 Enter 'exit' or a name to lookup: Claude Found Claude at 333-4340 Enter 'exit' or a name to lookup: Etheline Found Etheline at 333-4340 Enter 'exit' or a name to lookup: Fred Didn't find customer: Fred Enter 'exit' or a name to lookup: exit

Figure 23.7: This fully functioning Java example reads in data from a file and provides a lookup of a customer's phone number by the customer name or the name of his wife.

Several things in this example are worth noticing:

• Built-in string-manipulation functions that are used.
• The LineNumberReader object named in is an example of the tendency in Java to wrap one object in another object, and perhaps still another. Java developers frequently do this.
• In Java, the large standard class library almost always has just the right interface for the particular job.
• Although the Java example appears somewhat longer than the perl example, this is primarily due to the comments and structural aspects we used when writing it.

The programmer always needs to create a Java class, but this example is also different because we took a more object-oriented approach to the problem. We provided a CustomerLookup object that performed the work in a rather abstract way. The main routine simply creates a CustomerLookup object based on a file, and then uses the lookup method without concern for its internals.

That additional work can be viewed as pure overhead, or as good software design. In the case of this small example, it is probably more overhead. You can probably just as easily write a small program in perl or C as in Java. Because of its object-oriented nature, however, you might find it easier to write Java software that isolates its internal structures from other parts of the application.

Like perl, Java provides the ability to invoke a Qshell command. Figure 23.8 uses the Qshell system utility to interact directly with a CL command. Recall from chapter 22 that invoking the utility like this is a shortcut, which may use a temporary file to hold the output from a Qshell or CL command or utility.

pwd /home/jsmith/src cat com/mcpress/qshell/PtfStatus.java package com.mcpress.qshell; import java.util.*; import java.io.*; public class PtfStatus { public final static boolean debug = false; Hashtable ptfs; public PtfStatus() throws Exception { ptfs = new Hashtable(); String commandArray[] = new String[]{ "/usr/bin/system", "DSPPTF OUTPUT(*PRINT)" }; Runtime run = Runtime.getRuntime(); Process proc = run.exec(commandArray); // Since we're running a Qshell command, the process // will output EBCDIC data. We'll use an encoding of // Cp037 to read US Englich EBCDIC (CCSID 37) LineNumberReader in = new LineNumberReader (new InputStreamReader(proc.getInputStream(), "Cp037")); // Read each line. String line = in.readLine(); while (line != null) { if (debug) { System.out.println("<" + line + ">"); } // PTF list in the output is a 7 character name, // 2 alpha, 5 digits or // 3 alpha, 4 digits // prefixed by one space on each line. boolean isAPtf = true; isAPtf = isAPtf && Character.isSpace(line.charAt(1)); isAPtf = isAPtf && Character.isLetter(line.charAt(2)); isAPtf = isAPtf && Character.isLetter(line.charAt(3)); isAPtf = isAPtf && Character.isLetterOrDigit(line.charAt(4)); isAPtf = isAPtf && Character.isDigit(line.charAt(5)); isAPtf = isAPtf && Character.isDigit(line.charAt(6)); isAPtf = isAPtf && Character.isDigit(line.charAt(7)); isAPtf = isAPtf && Character.isDigit(line.charAt(8)); isAPtf = isAPtf && Character.isSpace(line.charAt(9)); if (isAPtf) { String ptf = line.substring(2, 9); String status = line.substring(14, 33); if (debug) { System.out.println("OUT: <" + ptf + ">, <" + status + ">"); } ptfs.put(ptf, status); } line = in.readLine(); } } public String getStatus(String name) { String status = (String)ptfs.get(name); if (status == null) { status = "Not Loaded"; } return status; } public static void main(String args[]) { if (args.length == 0) { System.err.println("Usage: java PtfStatus ..."); System.exit(1); } try { PtfStatus ptfs = new PtfStatus(); String status; System.out.println("------- --------------------"); System.out.println(" PTF Status "); System.out.println("------- --------------------"); for (int i=0; i status = ptfs.getStatus(args[i]); System.out.print(args[i]); System.out.print(" "); System.out.println(status); } // end of for (i=0 < args.length) } catch (Exception e) { e.printStackTrace(); System.exit(2); } System.exit(0); } // end of main } java com.mcpress.qshell.PtfStatus SI06971 SI06972 SI06973 SI06974 SI06975 SI06976 SI06977 ------- -------------------- PTF Status ------- -------------------- SI06971 Temporarily applied SI06972 Superseded SI06973 Not Loaded SI06974 Not Loaded SI06975 Temporarily applied SI06976 Temporarily applied SI06977 Superseded

Figure 23.8: This Java example demonstrates using the Runtime.exec() API to run a Qshell command and process the output.

Figure 23.8 uses the Runtime.exec() API to process the output from a Qshell command. The Qshell system utility is used to execute a CL command. The output is used to build a Hashtable containing the PTF (Program Temporary Fix) names and their statuses. The Hashtable serves as the lookup mechanism for the status of each randomly selected PTF. Compare and contrast this Java example with the similar perl example in Figure 22.9 and the C example in Figure 24.7.

Notice, in this example, that running a Qshell utility from within Java is almost as simple as in the perl program. You have to do a bit more processing related to the code page of the data sent back from the program, but the difficulty is minimal. Also, notice that the regular expression features of perl are missing (in Java 1.3). Although the method used here might perform better for this example, regular expressions would be a useful alternative to this model for finding a PTF in a line of text. Regular expression support is present in Java 1.4.

The Java language provides a standard way to access a database using JDBC ( Java Database Connectivity ) APIs. Figure 23.9 uses these APIs to demonstrate a more realistic phone-number lookup application than in Figure 23.7. The names and phone numbers reside in the relational database on the iSeries; Java is used to access this database. Compare and contrast this Java example with the similar perl example in Figure 22.10 and the C example in Figure 24.8.

pwd /home/jsmith/src cat com/mcpress/qshell/CustomerDBLookup.java package com.mcpress.qshell; import java.util.Hashtable; import java.io.*; import java.sql.*; // Get the JDBC classes public class CustomerDBLookup { public final static String NONE = "none"; Connection conn; PreparedStatement ps; static { // Load the JDBC driver that we're going to use. // JDBC drivers register themselves when loaded. try { Class.forName("com.ibm.as400.access.AS400JDBCDriver"); } catch (Exception e) { System.err.println("Didn't load the toolbox driver"); } } public CustomerDBLookup() throws SQLException { conn = DriverManager.getConnection("jdbc:as400:localhost"); ps = conn.prepareStatement ("SELECT PHONENUMBER FROM JSMITHQ.CUSTOMERS" + "WHERE NAME = ? OR WIFE = ?"); } public String lookup(String name) throws SQLException { // Everything is already created. Just set the parameters // and execute the statement. ps.setString(1, name); ps.setString(2, name); ResultSet rs = ps.executeQuery(); String phoneNumber = null; if (rs.next()) { // Get the first column from the first row of the result set. phoneNumber = rs.getString(1); if (phoneNumber == null) { // Found the customer, but no phone number phoneNumber = NONE; } } rs.close(); return phoneNumber; } public void close() { if (conn != null) { try { conn.close(); } catch (Exception e) { e.printStackTrace(); } } conn = null; ps = null; } public static void main(String args[]) { if (args.length != 0) { System.err.println("Usage: java CustomerDBLookup"); System.exit(1); } CustomerDBLookup list = null; try { String item; String name; list = new CustomerDBLookup(); // Get a 'nicer' interface over the System.in object // that represents standard input. We'll use LineNumberReader // just for fun. LineNumberReader in = new LineNumberReader(new InputStreamReader(System.in)); while (true) { System.out.println("Enter 'exit' or a name to lookup:"); Read the next name from standard input, any input // class (API) that could be constructed from System.in // could be used here. name = in.readLine(); if (name == null) { // All done. break; } if (name.equals("exit") name.equals("quit")) { break; } // Lookup the name item = list.lookup(name); if (item == null) { System.err.println("Didn't find customer:" + name); } else { if (item == NONE) { System.err.println("No listing for" + name); } else { System.out.println("Found" + name + "at" + item); } } } // Exit successfully. System.exit(0); } catch (Exception e) { System.err.println("Error occurred"); e.printStackTrace(); // Exit in error condition. System.exit(2); } finally { // Be sure to clean up any DB resources that were allocated. if (list != null) { list.close(); } } } // end of main } export CLASSPATH=/home/jsmith/src java com.mcpress.qshell.CustomerDBLookup Didn't load the toolbox driver Error occurred java.sql.SQLException: No suitable driver java/lang/Throwable.(Ljava/lang/String;)V+4 (Throwable.java:90) java/sql/SQLException.(Ljava/lang/String;Ljava/lang/String;)V+1 (SQLException.java:60) java/sql/DriverManager.getConnection(Ljava/lang/String;Ljava/util/ Properties;Ljava/lang/ClassLoader;)Ljava/sql/Connection;+ 243 (DriverManager. java:537) java/sql/DriverManager.getConnection(Ljava/lang/String;)Ljava/sql/ Connection;+12 (DriverManager.java:199) com/mcpress/qshell/CustomerDBLookup.()V+0 (CustomerDBLookup.java:22) com/mcpress/qshell/CustomerDBLookup.main([Ljava/lang/String;)V+0 (CustomerDBLookup.java:58) export CLASSPATH=/QIBM/ProdData/HTTP/Public/jt400/lib/jt400.jar: $CLASSPATH java com.mcpress.qshell.CustomerDBLookup Enter 'exit' or a name to lookup: Bill Found Bill at 333-4444 Enter 'exit' or a name to lookup: Daisy Found Daisy at 333-4444 Enter 'exit' or a name to lookup: Claude Found Claude at 333-4340 Enter 'exit' or a name to lookup: Etheline Found Etheline at 333-4340 Enter 'exit' or a name to lookup: Fred Didn't find customer: Fred Enter 'exit' or a name to lookup: exit

Figure 23.9: Use the database to perform the phone number lookup previously demonstrated using a Hashtable.

Except for the need to load the JDBC driver before accessing the database, this example looks similar to the perl program. The database-access APIs are object-based in both perl and Java, so they are very similar.

The Java program has some requirements with regard to exception-handling that aren't present in the other languages. Java exceptions eliminate some of the need for error-checking in the mainline program path . At times, handling exceptions for possible or expected error conditions can be slightly more complex in Java than error-checking in other languages.

The commands shown in Figure 23.9 also demonstrate the type of error that can occur if the CLASSPATH variable is not set up correctly:

java.sql.SQLException: No suitable driver

Fixing the CLASSPATH variable enables the example program to run successfully.

Summary

The Qshell environment is an integral part of Java application development. Java applications have built-in support for interacting with Qshell, and many Java commands are only accessible from within Qshell. The Java jar utility can serve as a general-purpose archive and file-compression utility.

Chapter 24 C and C++ Development Tools