Vaccess ProgramCall classes

The program call components in the vaccess package allow a Java™ program to present a button or menu item that calls a server program. Input, output, and input/output parameters can be specified using ProgramParameter objects. When the program runs, the output and input/output parameters contain data returned by the server program.

A ProgramCallButton object represents a button that calls an server program when pressed. The ProgramCallButton class extends the Java Foundation Classes (JFC) JButton class so that all buttons have a consistent appearance and behavior.

Similarly, a ProgramCallMenuItem object represents a menu item that calls an server program when selected. The ProgramCallMenuItem class extends the JFC JMenuItem class so that all menu items also have a consistent appearance and behavior.

To use a vaccess program call component, set both the system and program properties. Set these properties by using a constructor or through the setSystem() and setProgram() methods.

The following example creates a ProgramCallMenuItem. At run time, when the menu item is selected, it calls a program:

                       // Create the ProgramCallMenuItem
                       // object. Assume that "system" is
                       // an AS400 object created and
                       // initialized elsewhere. The menu
                       // item text says "Select Me", and
                       // there is no icon.
     ProgramCallMenuItem menuItem = new ProgramCallMenuItem ("Select Me", null, system);

                       // Create a path name object that
                       // represents program MYPROG in
                       // library MYLIB
     QSYSObjectPathName programName = new QSYSObjectPathName("MYLIB", "MYPROG", "PGM");

                       // Set the name of the program.
     menuItem.setProgram (programName.getPath());

                       // Add the menu item to a menu.
                       // Assume that the menu was created
                       // elsewhere.
     menu.add (menuItem);

When a server program runs, it may return zero or more server messages. To detect when the server program runs, add an ActionCompletedListener to the button or menu item using the addActionCompletedListener() method. When the program runs, it fires an ActionCompletedEvent to all such listeners. A listener can use the getMessageList() method to retrieve any server messages that the program generated.

This example adds an ActionCompletedListener that processes all server messages that the program generated:

                       // Add an ActionCompletedListener
                       // that is implemented by using an
                       // anonymous inner class. This is a
                       // convenient way to specify simple
                       // event listeners.
     menuItem.addActionCompletedListener (new ActionCompletedListener ()
     {
          public void actionCompleted (ActionCompletedEvent event)
          {
                       // Cast the source of the event to a
                       // ProgramCallMenuItem.
               ProgramCallMenuItem sourceMenuItem = (ProgramCallMenuItem) event.getSource ();

                       // Get the list of server messages
                       // that the program generated.
               AS400Message[] messageList = sourceMenuItem.getMessageList ();
               
                       // ... Process the message list.
          }
     });
Parameters

ProgramParameter objects are used to pass parameter data between the Java program and the server program. Input data is set with the setInputData() method. After the program is run, output data is retrieved with the getOutputData() method.

Each parameter is a byte array. It is up to the Java program to convert the byte array between Java and server formats. The data conversion classes provide methods for converting data.

You can add parameters to a program call graphical user interface component one at a time using the addParameter() method or all at once using the setParameterList() method.

For more information about using ProgramParameter objects, see the ProgramCall access class.

The following example adds two parameters:

                       // The first parameter is a String
                       // name of up to 100 characters.
                       // This is an input parameter.
                       // Assume that "name" is a String
                       // created and initialized elsewhere.
     AS400Text parm1Converter = new AS400Text (100, system.getCcsid (), system);
     ProgramParameter parm1 = new ProgramParameter (parm1Converter.toBytes (name));
     menuItem.addParameter (parm1); 

                       // The second parameter is an Integer
                       // output parameter.
     AS400Bin4 parm2Converter = new AS400Bin4 ();
     ProgramParameter parm2 = new ProgramParameter (parm2Converter.getByteLength ());
     menuItem.addParameter (parm2);

                       // ... after the program is called,
                       // get the value returned as the
                       // second parameter.
     int result = parm2Converter.toInt (parm2.getOutputData ());
Examples

Example of using a ProgramCallButton in an application. Figure 1 shows how the ProgramCallButton looks:

Figure 1: Using ProgramCallButton in an application

Using ProgramCallButton in an application