Are you a Java developer looking to retrieve iSeries TCP/IP system API information? If so, this article is definitely for you. Here, you'll learn how to use Java Toolbox  to retrieve information using the TCP/IP management APIs that have been available since OS/400 V5R1.

Depending on the type of application a customer is creating, you can obtain certain iSeries system information. For instance, in a sockets application that allows many customers to connect to your iSeries system, you may want to monitor what IP address and Media Access Control (MAC) address is connecting to your system. An IP address is a network identifier that can be assigned to a system. The MAC address is the physical address that is burned into a computer's network card. If a client that connects to your iSeries socket application is doing something that makes you feel uncomfortable, you can retrieve its IP and MAC addresses using one of the iSeries TCP/IP system APIs.

When a client connects to your iSeries system from an external network for the first time, an ARP REQUEST must be sent out from your iSeries system to map the client's MAC address with its IP address. When your system receives an ARP REPLY with the MAC address, that value is put into the ARP table of the iSeries system. When the client connects again, it won't be necessary to send another ARP REQUEST to find the client's MAC address. On the iSeries, the TCP/IP system API called QtocLstPhyIfcARPTbl lists all the data for the iSeries ARP table.

When using system APIs, you need to know how to call them and what information to input. The QtocLstPhyIfcARPTbl requires a user space name, a format name, and a line name, as shown in the table below. If any problems occur when calling the API an error code will be outputted so you don’t have to worry about any input value to place within the error code.

Service Program: QTOCNETSTS
Threadsafe: Yes


When calling the QtocLstPhyIfcARPTbl, you must put all the information into a predefined user space that you can create on the iSeries system.

A format name is also required because many iSeries system APIs have different formats. It is important to know the format because, when the API is called, all the information gets put in a predefined location within the user space. To retrieve that information, you need to know the exact decimal number within the user space. Within the QtocLstPhyIfcARPTbl, there is only one format name, ARPT0100 (see the table below).

The third parameter is the line name. When inputting this value, you can hard-code it in if you know it will not change or you can call the Retrieve Line Description (QDCRLIND) API, which will allow you to return the name of your line description. If you are designing a GUI, you can allow a user to choose among a number of line names for a particular iSeries system.

Using the Java Toolbox

Now that you understand how the system API works, you can put Java Toolbox to work. Java Toolbox has an API called ProgramCall. The ProgramCall class allows a user to call an iSeries system API, pass parameters to it (input and output), and access data returned in the output parameters after the program runs. Use ProgramCall to call programs; use ServiceProgramCall to call service programs. You will notice in the first table that the QtocLstPhyIfcARPTbl API has a service program called QTOCNETSTS. Since it's a service program, you will use the ServiceProgramCall.

Take a look at some of the code that allows you to call the QtocLstPhyIfcARPTbl and retrieve data back from the user space. Remember, before calling this system API, you need to create a user space. Java Toolbox has a UserSpace class that allows you to do just that. In the following method (Figure 1), you will see that I created a UserSpace object called ARP in library GARBERSB.

Figure 1: Use this code to create a user space.

Once the user space is created, you can fill in your system API parameters. First, define the ProgramParameter array with a length of 4. Note that the AS400 system object has been pre-created. This is shown in Figure 2.

Figure 2: This code sets the ProgramParameter array.

Once you have your ProgramParameter set up, all you have to do is create and call the ServiceProgramCall. It is important to make sure you catch possible AS400Messages that might end up getting thrown for debugging purposes. See Figure 3.

Figure 3: Call the service program.

Now that you have called the QtocLstPhyIfcARPTbl, you can retrieve the information that was put within your user space. Figure 4 shows how you can retrieve certain information from the user space.

Figure 4: Retrieve information from your predefined user space.

As you can see, you can keep on increasing the index by the decimal offset value of the API.

Figure 5 shows an example of what happens when you run the example code. Note that you will have to log onto an iSeries system that has a release of V5R1 or later.

Figure 5: This output is a result of the example code.

In the example output, you now see that the IP address 9.5.4.129 is within the ARP table with a MAC address of 00:00:0C:07:AC:01. You can implement this information within your socket application, possibly disconnecting it and not letting it connect in the future if the client is doing something malicious.

Now that you know how to program the QtocLstPhyIfcARPTbl API, you should be able to move on to program different iSeries system TCP/IP APIs. All of the TCP/IP APIs can be viewed within the iSeries Information Center. Many of the APIs can be useful when you want certain information to be retrieved within your application.

Benjamin Garbers is a Software Engineer within the Rochester Support Center. He is currently developing Internet applications for IBM's iSeries Technical Web site.