Tools from iSeries Java Toolbox: Pinging iSeries Services

by Kevin Vandever

If your IT shop is anything like the one I work in, the iSeries is only one of many platforms used to run the business. However, it is still probably the primary platform in your shop, and as such it contains the bulk of the business data and logic. Applications on other platforms depend on that business data and logic, so they require the iSeries to be available as much as possible. I'm going to show you a simple way, using Java, to monitor iSeries services, which will help you to discover potential connectivity and resource availability problems before your production applications do.

The Toolbox

IBM's iSeries Toolbox for Java is a set of Java classes used to access a variety of iSeries services. For a detailed explanation of the toolbox, check out my article "Calling a Program Using the iSeries Toolbox for Java" or visit the IBM Toolbox for Java site. In this article, I am going to focus on one of the classes contained within the toolbox. This class allows you to ping, or check, iSeries services to see if they are available. This class is a new feature that was added to the V5R1 release of the toolbox, so you will need that version to use this technique.

An Ounce of Prevention

Say you use the iSeries toolbox to send requests to, and receive responses from, the iSeries via a data queue. If the iSeries is down for some reason, if the communication link is broken, or the specific port used to listen for data queue traffic is inactive, your production application probably traps for errors and handles them in an appropriate fashion. Maybe it writes to a log file, tries the request again, or attempts to contact a support person. Whatever the case, the customer has been affected because the transaction was not completed and, depending on how long it takes for someone to react to the problem, additional customers could be affected without your knowledge. Using the AS400 Java Ping (AS400Jping) class, you can set up a monitoring system that will tell you when the iSeries, or any one of the iSeries services, is unavailable.

Ping400 is a simple Java class that I wrote to ping every iSeries service and display a message telling me if that service is available or not. The class accepts an IP address or host name of the iSeries you want to ping. To run Ping400, use the following Java command:

java Ping400 myas400

A Little Code Goes a Long Way

Ping400 is the class name and myas400 is the host name of the iSeries you want to ping. You can also use an IP address if you don't know or have a host name. Let's take a look at the code. I am going to assume some Java knowledge while explaining this code; if you are not that familiar with Java but still want to use this tool, refer to my article "Java Concepts for iSeries Programmers" for an introduction on installing and using the Java language.

Back to the code. The AS400JPing class and necessary constants reside in the com.ibm.as400.access package, so that package must be imported to the application. I have defined a main method that allows me to call this class from the command line and accept an array of string objects. (A string object is simply some text. Each string is separated by white space.) The following "if" logic ensures that I enter at least one parameter from the command line:

if (args.length == 0)
        {
          System.out.println("Come on, throw me a bone here! I need an 
IP                                                          
          address or system name.");
          return;
        }

If I don't type a parameter after the class name on the command line, the above message will display and the application will end.

Now take a look at the "try" block. The first thing I do is to create an AS400JPing object called pingobj and instantiate it with the iSeries name or IP address entered on the command line. The following line of code takes care of that for me:

AS400JPing pingObj = new AS400JPing(args[0]); 

The AS400JPing class accepts two additional, optional parameters. The first optional parameter is the iSeries service you want to ping, and the second is whether or not you want to use secure sockets to do the pinging. The iSeries service parameter is in the form of an integer constant, and the secure sockets parameter is a Boolean true or false. It defaults to false.

Now it's time to ping the services. There are eight services that handle all the different iSeries service requests. They are represented by constants in the toolbox, and each constant corresponds to a specific service on the iSeries. Let's take a look at the logic used to ping the data queue service:

if (pingObj.ping(AS400.DATAQUEUE))
            System.out.println("The AS/400 Data Queue Service.... on " 
+ 
            args[0] + " is AVAILABLE!");
else
            System.out.println("The AS/400 Data Queue Service.... on " 
+ 
            args[0] + " is NOT Available!");

I call the ping method from the pingobj object I created earlier and pass it the AS400.DATAQUEUE constant to ping the data queue service on my iSeries. It returns a Boolean true or false, and that is why I can call the ping method as a part of the "if" statement. I then display a message based on whether or not the ping was successful. I then perform a ping to the other services (there are seven) and display appropriate messages for each service. If I call the ping method and pass it no parameter, it pings all the services and returns a true value only if all services are available.

Most of the service constants, such as AS400.DATAQUEUE and AS400.SIGNON, are self-explanatory, but others might not be as obvious, so allow me to provide a brief explanation of each service:

Only the Beginning

I have shown you a simple example of how to ping iSeries services using Java. You may want to kick this technique up a few notches and display the information in HTML or in JavaServer Pages. If so, check out one of Shannon O'Donnell's or Richard Shaler's articles from previous issues. Once you're displaying the information in a Web page, you may then want to refresh the information every so often to get a dynamic picture of your iSeries status. The options are endless. Enjoy!