Midrange Programmer

In "Prompting iSeries Commands in Java," I provided a technique for prompting and running iSeries commands from Java using the iSeries Toobox for Java. If you had a chance to check out the code you may have noticed that it was rather simple and pretty high-level. You also may have noticed that, "out of the box," the help text didn't work. In this article, I'll not only show you how to add the help function to your application but also explain a little of what's going on behind the scenes.

The more I've worked with Java, the more I'm impressed. That's because I like to solve problems for users and customers. As interesting as the underlying technology is, I don't want to necessarily figure it all out before I can do my job. Yes, I like to eventually know a little of what's going on behind the scenes--that's the purpose of this article--but the ultimate goal is to solve some problem or aid the customer or user. Java allows me to do that. When I first used the prompting code I was amazed at how simple it was. Once I got it working I was able to try to understand how it was put together. The same went for the help text. I was expecting this to be the hardest part, but because of Java's object-oriented capabilities, adding help was as simple as downloading the necessary JAR files from Sun Microsystems' Web site and adding them to my CLASSPATH. So where are the necessary help files? You can find them on Sun's JavaHelp site. Once there, you can download the Zip file and follow the instructions on the download site to install JavaHelp on your workstation. After installing the JavaHelp software, you will need to add a JAR file to the end of your CLASSPATH. The entry will look something like the following:

The jh1.3.3 is whatever you name your JavaHelp home directory. It could be different from mine. The rest of the entry should look just as mine does. Now for the modifications to the original Java application, Prompter. Are you ready? Ok, you're done. That's right, there are no modifications necessary. Apparently, the Jframe class used to build our help applet has the appropriate help-related method calls already built in. If you remember from the last article, before we installed the JavaHelp software, we could press the Help button, which means the foundation had already been set for help. Nothing happened, because you didn't have the appropriate JAR files installed. Let's test it out. Run the Prompter application, like so:

Now, when the SBMJOB applet is displayed, press the Help button and--voila!--Help text is displayed. From the help text window you can print the information for future use. Now look at button marked with a question mark (?). This is field level help. The way you use it is to click a specific field, then click the field level help button and drag the question mark to that field. When you release the mouse, specific help for that field will be displayed. Pretty cool, huh? And all without any coding on your part. Adding help text may not always be this easy, but as you mess with this more, and want to do more things with help, make sure you visit the JavaHelp site to get more details.

As you may have guessed, there is a lot happening behind the scenes when command prompting is executed. But what kinds of things are they? Well, first there is the Jframe object and all its magic to create the window and help capability, but I usually let that go, happy and appreciative that it works. Other things the DOS screen tells you about what is going are how many panels are being loaded, how many bytes are sent and returned to and from the iSeries, and any error message that come up. What I'm interested in is some of the iSeries-related tasks going on. Let's look at two of them, which will help us understand how it all works. First, take a look closely at the messages on the DOS screen. When you first prompt a command you will see a call to the QCDRCMDD API. This API retrieves command definitions and is the method used to get the information for your prompt window. When you press any of the help buttons, another API is called to retrieve the help text from the iSeries. That API is QUHRHLPT. The DOS screen even tells you how many bytes of help text were returned and the format used with the QUHRHLPT API. For more information on APIs, check out the IBM iSeries Information Center. The V5R2 version of the information center has a very cool API finder. The second technology I was interested in was to find out how the APIs were being called. There is a nice hint right there in the DOS screen, "Beginning PCML call. . . ," and right under that, "Constructing ProgramCallDocument for QCDRCMDD API. . . ." Under that, you see the message stating that the call to API is being made. Well, PCML and ProgramCallDocument are things near and dear to me because I have used them many times to call RPG programs from Java. Basically, it is a way to use XML and the Java Toolkit for iSeries to call iSeries programs. You can find out more about that subject in "Calling a Program Using the iSeries Toolbox for Java."

From these hints on the DOS screen, you can now start to see how this process works and how to create your own applications based on the same technologies. Now that we have our help text and understand a little more about the guts of the process, let's look at the actual help windows.

Last time, I did not get the chance to talk about the features available to you from the prompted iSeries command. Let's use SBMJOB as an example, because it best illustrates these capabilities. First of all, take a look at the menu options at the top of the Help screen. And if you haven't done so, prompt the SBMJOB command so you can follow along at home. OK, back to the menu. File and Edit are pretty straightforward, as you have these options with almost any window you use. The interesting thing to note is that under the File menu, Cancel F12 is listed, instead of the normal Close or Exit option. This is not only nice that iSeries jargon is used, but you also may have realized that this means that F12 can be used to exit out of the Help screen. Try it! Let's move to the View menu option. From here you can do a bunch of things also available in the green-screen, 5250 version of command prompting. You can view the advanced options, all options, the keywords, as well as reset the options to their original state. Notice, too, that the corresponding function keys--F10, F9, F11, and F5 respectively--are also available. The last option on the View menu that I want to talk about it the Command String option (Shift-F2). Taking this option will allow you to see the command string that has been built so far. You can use this for leisure, but you may want to copy and paste this command string to use somewhere else within the application or for user documentation. The Help menu is also pretty simple. You can choose to view help from this menu option. Notice that F1 is the hotkey for help. Sound familiar? The main thing I want to show you on this menu is the help-about-help option. From here you can display a window discussing the features I just discussed, so if you don't believe me, want a second opinion, or want to print out a handy-dandy cheat sheet, you can do it from this option.

OK, now for the actual Help window. I've already discussed how to use the help buttons, so the only other button is the Advanced button. This button works the same as if you pressed F10 or chose Advanced from the View menu option. The other cool thing about this help text, and why I asked you to use SBMJOB, is the ability to prompt within the prompt screen. We have this ability on the green-screen versions, but it's nice that it's still available to us now. Type any old command in the command parameter, then press F4. What happens? You get prompted for that command, just like you do in a green-screen environment. How about that? As for the rest of the Help screen, it works pretty much like its green-screen counterpart except that you can choose to use a list box, instead of F4, to prompt for a valid entry to a given parameter. You can also still use F4.

The primary reason for this article was not only to add help text, but to give you an understanding of what goes on behind the scenes and to show you that you don't lose functionality just because you're not using the green-screen versions of commands and programs. My hope is that the information will help you to extend the awesome resources of your iSeries beyond the reaches of its walls. Take some time to mess with this stuff. I think you'll find it to be useful.