Sometimes it seems as if getting a Java application to compile and run on the iSeries is more difficult than learning the Java language itself. I've downloaded working code only to have problems getting it to compile or run on the iSeries. Most of these issues stem from not having my CLASSPATH environment variable set correctly. So I thought I would show you a few ways to set your CLASSPATH, so you can get busy concentrating on what the heck your Java code is doing.

What is a CLASSPATH?

A CLASSPATH works much like an OS/400 library list. If you want to compile and run Java, you must tell the Java Virtual Machine, or JVM, where to find your source code, as well as any other classes or objects that are required by your application. You do this with the CLASSPATH environment variable. As with a library list, where you list the libraries through which the compilation or operation of a program will search for the necessary OS/400 objects, the CLASSPATH allows you to enter OS/400 IFS directories through which your Java compilation or operation will search for its necessary objects and classes. Another feature of the CLASSPATH is that in addition to a directory structure, you may also list specific Java Archive (.jar) files or zip files within a directory. For more information on JAR and zip files, check out my article "Java Concepts for iSeries Programmers."

While I'm comparing the CLASSPATH environment variable to an iSeries library list, I must mention that both have a system portion, which is separate from a user's job portion. In the case of the CLASSPATH variable, the default system CLASSPATH is system-defined and specifies where the JVM can find the IBM Developer Kit, the Remote Abstract Window Toolkit, and many other system classes.

Setting the CLASSPATH

OK, enough theory. Let's get down to setting the CLASSPATH environment variable. Probably the most comfortable way, because most of us are accustomed to OS/400 commands, is to use the Work with Environment Variables (WRKENVVAR) command. Using this command, you can add, change, or delete any environment variable, but since, for now, I am only interested in the CLASSPATH, that's all I am going to concentrate on. The following figure shows the first step to adding the CLASSPATH:

From this screen, I am going to add the CLASSPATH by placing a 1 in the option field and the constant, CLASSPATH, in the name field. Notice, at the top of the screen, that you are performing this task for *JOB. If you prompt on the WRKENVVAR command, you are given the option to set the CLASSPATH for your *JOB or for the system (*SYS). We are only focusing on *JOB in this article. The next thing you want to do is press Enter to display a screen like the one shown here:

In the initial value field, type your specific CLASSPATH, separated by colons (: ). Notice in the previous figure that I am pointing to two different JAR files in the same directory structure. A colon separates each reference to a JAR file. In library list speak, this CLASSPATH entry is almost the equivalent of two libraries. I say almost equivalent because, with iSeries library lists, you cannot reference a specific program or file as you can with the CLASSPATH. Press Enter and your CLASSPATH is set for your job.

You can also use the Add Environment Variable (ADDENVVAR), Change Environment Variable (CHGENVVAR), and Remove Environment Variable (RMVENVVAR) commands to perform the same tasks as options 1, 2, and 4 in the WRKENVVAR command respectively.

While we're on the subject of OS/400 commands, there are a couple of other ways to set the CLASSPATH, on the fly, during compilation or operation. The run java (RUNJVA) and create java program (CRTJVAPGM) commands contain a parameter to use the CLASSPATH environment variable, which you now know how to set, or to set your own CLASSPATH for the duration of that specific job. If you decide not to use the CLASSPATH environment variable, you enter your class path entries just as you did inside the WRKENVVAR command.

For those of you who are Unix savvy or have read Ted Holt's articles in this newsletter and are now Qshell savvy, there are some ways to set your CLASSPATH from the Qshell environment. One way is to use the export command with the –s option:

The –s option tells the export command that you are modifying the CLASSPATH. You can also modify and view other settings using this command, but the –s option is what I am concerned with here. Type export with no parameters to see some of the other settings you can view and manipulate. Notice also the period (.) that starts off the CLASSPATH definition. This is a shortcut for your current working directory. The colon separates each entry in the CLASSPATH.

You can also modify the CLASSPATH during compilation or runtime in Qshell, just as you could with OS/400 commands. Both the javac, which is used for compiling Java source code, and java, which is used for running java applications, commands contain a –classpath option. This option allows you to append CLASSPATH entries to the system default CLASSPATH. It does not override the CLASSPATH environment variable. This is different--and is the only difference--from the way the javac and java commands are implemented by Sun Microsystems. Sun's versions of javac and java allow you to override the CLASSPATH by using the –classpath or –cp option. It's just something to note.

The last method I want to show you employs the ADDENVVAR command along with a new OS/400 command. The beauty of this technique is that it is wrapped up in a CL program that can then be part of your startup job when you sign on. That way, you don't have to worry about your CLASSPATH environment variable unless your actual Java environment changes. Take a look at the source code in SETCLSPTH. I use the ADDLNK command, which allows me to take a directory structure and give it a symbolic name. Then I can use that symbolic name inside of my CLASSPATH entry, instead of retyping the directory structure each time. This is very helpful if you have a long directory structure and you need to reference multiple JAR files within that structure. You can define it once using the ADDLNK command and reference that simple name multiple times in your CLASSPATH definition. That's what I've done in my CL program. I have defined a link called JAVA_HOME, and I use that link in my CLASSPATH definition instead of typing the five-deep directory structure multiple times. You should recognize the usage of the ADDENVVAR command, so I won't cover it again.

Decisions, Decisions

Depending on your application, there may be other environment variables that you may need to tinker with, but the CLASSPATH is the one that will solve most of your Java compilation mysteries and may even help you at run time. There are also other methods to set the CLASSPATH environment variables using tools such as Qshell scripts and the iSeries Toolbox for Java, but the information in this article should provide with you with a good start. Give them all a whirl and find out which one works best for your environment.