Midrange Programmer

I was poking around the "what's new in this release" portion of the V5R2 iSeries Toolbox for Java documentation because of some serious research I was involved in (OK, I was looking for a topic for this article and came across a new Java class that I have been waiting for). This class adds much-needed flexibility to the method currently used to run an iSeries command from a Java application. Come check it out.

For a long time, we have had the ability to run iSeries commands from Java in an asynchronous, or batch-like, environment. What I mean is that we can run any command that doesn't require a 5250 data stream for its output. For example, running the DSPMSG command from Java using the CommandCall class does you no good unless you run that command using the *PRINT option. Then you can use another method--maybe other Java classes--to view that printed result. The problem is that you have to know the exact command string to run, because there is no prompting. This isn't too bad when running simple commands. Using the DSPMSG command, it's not a big deal to run the command:

In fact, you could probably live a comfortable life running that command without ever having the ability to prompt it. However, running more complicated commands makes things more difficult and less flexible. The SBMJOB command comes to mind. There are many options from which to choose when running the SBMJOB command, and even if you've worked it all out so that you take all the defaults and only need to supply the actual command, there is still the problem of prompting that command. For example, what if you were submitting the Copy File (CPYF) command? Not only does the submit job have many options, but so does the CPYF command. So unless you always run CPYF and SBMJOB exactly the same way, every time, you may desire the need to prompt one or both of these commands.

That's where the CommandPrompt class comes in. This class allows you to prompt a command before running it. We've had this capability forever on the iSeries and its predecessors, but this is a new, and welcomed, feature for the access-iSeries-from-Java world. Before I jump into the code and show you the class in action, I will first talk about the steps you need to take to set up your environment.

I know you out there. You've probably already downloaded the code and tried to get it to run. Aha! You probably ran into some snags, too. If not, you already have a very complete Java environment set up and I commend you. But for rest of us, there are some things we have to do before we can move on.

I am assuming that you already have the Java development environment installed on your workstation. If not, you definitely need to do that first. Check out "Java Concepts for iSeries Programmers" for details on the Java language and how to download and install the development and runtime environments.

Once you have the java and java toolbox libraries installed, you need to set your CLASSPATH appropriately. There article "How Do I Set My CLASSPATH? Let Me Count the Ways" explains the theory behind the CLASSPATH environment variable, but it is geared more toward setting the CLASSPATH on the iSeries. To set your CLASSPATH on a Windows NT, 2000, or XP machine, click Start, Settings, then Control Panel. From the Control Panel, double-click the System icon and click the Advanced tab on the System Properties window. Click the Environment Variables button to get a list of your system and user-specific environment variables. This is where you need to edit your current CLASSPATH variable or create a new one. If you don't know how to do this, please refer to the installation and setup documentation in either the javadoc from Sun Microsystems or the iSeries Toolbox documentation. OK? Let's move on.

There are two additional toolbox JAR files that you need to include in your CLASSPATH environment variable in order to run the Java application for this article. These are in addition to the core toolbox JAR, jt400.jar; the folder or folders where your applications exist; and the core folders and JAR files for your Java development and runtime environments. They are jui400.jar and util400.jar.

Now you are almost ready. However, there is one more sticking point, another undocumented requirement to run this application. And that is to include the xerces XMLParser class in your CLASSPATH. It is needed because there is some XML parsing going on with regard to the call and subsequent return of information among the iSeries APIs. Without this class, the Java application would compile successfully, but would not run. I ended up downloading the Xerces-J project from Apache. From this site, download the 1.4.4 version, including the documentation, and follow the installation instructions. There is a newer version, 2.3.0, but I couldn't find the necessary class in that version and still had trouble running my application. The 1.4.4 version contained what I needed. Once you have that installed, you can add the following JAR file to your CLASSPATH: xerces.jar.

Don't forget to include the location of your JAR file. For example, if your JAR file exists in folder xerces-j_1_4_4, then your entry in the CLASSPATH variable would look something like this:

Whew! Now that your environment is ready to go, let's take a look at the code and what I am trying to accomplish with that code.

The purpose of my Java application, Prompter, is to allow you to prompt any iSeries command, change the necessary parameters, and run the command. As I stated earlier, we've had the ability to run commands for a long time. It is only now that we have the ability to prompt those commands before running them. A side benefit to this class is that it allows you to view the command string you are building, as you are building it. This further allows you to build command strings that can be copied and pasted into other applications that aren't ready or don't need the prompting capability. Of course, you can always build the command string from a green screen, but know you how Java folks feel about green screens. In fact, we all seem to be stricken with green-screen phobia these days. My digression aside, the ability to view your command string as it's being built may be a benefit for you.

Let's take a closer look at the code to see what it is doing. This code was provided by IBM and included with the documentation, so as hard as it was to set up the environment, it was that easy to come up with a little example to use. Thank you, IBM.

I'll gloss over the first part of the code. You can see what packages you have to include in order to use the AS/400 connection classes, the CommandCall and CommandPrompter classes, and the AS/400 message classes, which are optional but are nice to have if you want to display AS/400 messages when an error occurs. Next come the packages necessary to build the GUI that will display our prompted commands.

In the main method, the GUI object, frame, is instantiated. Next, a couple of content and layout methods are run. Next the AS/400 object, system, is instantiated with the system IP address and optional user ID and password. If you don't include the user ID and password, you will be prompted for them. What I usually do is include the system IP and user ID as parameters when the object is instantiated and I then get prompted for a password at runtime. After the AS400 object is defined, the cmdName object is instantiated with the information entered by the user on the command line.

The rest of the code looks pretty basic, but, as you'll see when you run the application, there is a lot going on behind the scenes. The commandPrompter object, cp, is instantiated and accepts the frame, system, and cmdName objects as parameters. Remember, these objects have already been created earlier in the application.

Then the command string is retrieved so that it can be displayed to the person who ran the application. The cmdString object contains the commands string after the command was prompted and possibly changed. The cmdName object contains the original command requested by the user for prompting. Finally, the command is run and any error messages returned from the AS/400 are displayed to the user.

Remember, the Java application is case-sensitive, so make sure to enter it in the compile and run commands as you named it when you downloaded it.

To run the command, use the java command followed by the iSeries command you want to prompt. To prompt the SBMJOB command, type the following on the command line:

The command string is not case-sensitive; it works just fine by entering either sbmjob or SBMJOB. Once you press Enter, you will be prompted for any sign-on information you did not include in the code. After you sign-on you should get a GUI representation of the prompted iSeries command. From here you can change parameters and run or cancel the command, among many other options. If you happen to misspell a command when you run the application, or don't have authority to that command, you will get a nice message telling you so. This is because I used the AS/400 message classes in the application. If you don't use the AS/400 message classes, your application will bomb and you won't know why.

For those who run commands from Java applications on a regular basis, the commandPrompt class is a much-needed improvement. For those who don't, this new feature to the Toolbox might open some doors for you. I have provided the basics for you to start prompting and running iSeries commands, so give it a try. One thing you may notice is that when you press the Help button on your GUI, no help is displayed. You will see error messages on the DOS screen, but you will still be able to run your command. Help is not part of the "out of the box" solution with the commandPrompt class. Next time, I will show you how to add that logic to your application so that you can use both the generic and field-specific Help buttons. I will also explain all that stuff happening behind the scenes, the stuff you see on the DOS screen while running the application. And, finally, for those who haven't had the chance to dig in, I'll explain some of the features available to you from the GUI version of the prompted command.