com.ibm.as400.access

Class ProgramCall

  • java.lang.Object
    • com.ibm.as400.access.ProgramCall
  • All Implemented Interfaces:
    java.io.Serializable
    Direct Known Subclasses:
    ServiceProgramCall


    public class ProgramCall
    extends java.lang.Object
    implements java.io.Serializable
    The ProgramCall class allows a user to call an IBM i system program, pass parameters to it (input and output), and access data returned in the output parameters after the program runs. Use ProgramCall to call programs. To call service programs, use ServiceProgramCall.

    The following example demonstrates the use of Program Call:

        // Call programs on system named "Hal."
        AS400 system = new AS400("Hal");
        ProgramCall program = new ProgramCall(system);
        try
        {
            // Initialize the name of the program to run.
            String programName = "/QSYS.LIB/TESTLIB.LIB/TESTPROG.PGM";
            // Set up the 3 parameters.
            ProgramParameter[] parameterList = new ProgramParameter[3];
            // First parameter is to input a name.
            AS400Text nametext = new AS400Text(8);
            parameterList[0] = new ProgramParameter(nametext.toBytes("John Doe"));
            // Second parameter is to get the answer, up to 50 bytes long.
            parameterList[1] = new ProgramParameter(50);
            // Third parameter is to input a quantity and return a value up to 30 bytes long.
            byte[] quantity = new byte[2];
            quantity[0] = 1;  quantity[1] = 44;
            parameterList[2] = new ProgramParameter(quantity, 30);
            // Set the program name and parameter list.
            program.setProgram(programName, parameterList);
            // Run the program.
            if (program.run() != true)
            {
                // Report failure.
                System.out.println("Program failed!");
                // Show the messages.
                AS400Message[] messagelist = program.getMessageList();
                for (int i = 0; i < messagelist.length; ++i)
                {
                    // Show each message.
                    System.out.println(messagelist[i]);
                }
            }
            // Else no error, get output data.
            else
            {
                AS400Text text = new AS400Text(50);
                System.out.println(text.toObject(parameterList[1].getOutputData()));
                System.out.println(text.toObject(parameterList[2].getOutputData()));
            }
        }
        catch (Exception e)
        {
            System.out.println("Program " + program.getProgram() + " issued an exception!");
            e.printStackTrace();
        }
        // Done with the system.
        system.disconnectAllServices();
     

    NOTE: When getting the AS400Message list from programs, users no longer have to create a MessageFile to obtain the program help text. The load() method can be used to retrieve additional message information. Then the getHelp() method can be called directly on the AS400Message object returned from getMessageList(). Here is an example:

        if (program.run("myPgm", myParmList) != true)
        {
            // Show messages.
            AS400Message[] messageList = program.getMessageList();
            for (int i = 0; i < messageList.length; ++i)
            {
                // Show each message.
                System.out.println(messageList[i].getText());
                // Load additional message information.
                messageList[i].load();
                //Show help text.
                System.out.println(messageList[i].getHelp());
            }
        }
     

    NOTE: When the program runs within the host server job, the library list will be the initial library list specified in the job description in the user profile.

    NOTE: There are two ways to run a program in an iasp. Users can call a program directly with path prefixed with the iasp information like "/IASP1/QSYS.LIB/TESTLIB.LIB/TESTPROG.PGM". Users can also call AS400.setIASPGroup to set the asp group information firstly, then call the program in regular library-qualified object name syntax. The second way is recommended. For example:

        // Call a program on system named "Hal" on asp "iasp1"
        AS400 system = new AS400("Hal");
        system.setIASPGroup("iasp1"); //If do not use *CURUSR for current library and library list, call other setIASPGroup interfaces.
        ProgramCall program = new ProgramCall(system);
        program.setProgram("/QSYS.LIB/TESTLIB.LIB/TESTPROG.PGM");
     
    See Also:
    ProgramParameter, AS400Message, ServiceProgramCall, Serialized Form
    • Method Summary

      Methods 
      Modifier and Type Method and Description
      void addActionCompletedListener(ActionCompletedListener listener)
      Adds an ActionCompletedListener.
      void addParameter(ProgramParameter parameter)
      Adds a ProgramParameter to the parameter list.
      void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
      Adds a PropertyChangeListener.
      void addVetoableChangeListener(java.beans.VetoableChangeListener listener)
      Adds a VetoableChangeListener.
      void cancel()
      End program call if the time exceeds the specified time
      AS400Message[] getMessageList()
      Returns the list of messages returned from running the program.
      int getMessageOption()
      Returns the option for how many messages will be retrieved.
      ProgramParameter[] getParameterList()
      Returns the list of parameters.
      java.lang.String getProgram()
      Returns the integrated file system pathname for the program.
      Job getServerJob()
      Returns a Job object which represents the server job in which the program will be run.
      AS400 getSystem()
      Returns the system on which the program is to be run.
      java.lang.Thread getSystemThread()
      Returns the thread on which the program would be run, if it were to be called on-thread.
      int getTimeout()
      Gets a valid time
      boolean isRunning()
      Check if the program is still running
      boolean isStayOnThread()
      Indicates whether or not the program will actually get run on the current thread.
      boolean isThreadSafe()
      Deprecated. 
      The name of this method is misleading. Use isStayOnThread() instead.
      void removeActionCompletedListener(ActionCompletedListener listener)
      Removes the ActionCompletedListener.
      void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
      Removes the PropertyChangeListener.
      void removeVetoableChangeListener(java.beans.VetoableChangeListener listener)
      Removes the VetoableChangeListener.
      boolean run()
      Runs the program on the system.
      boolean run(java.lang.String program, ProgramParameter[] parameterList)
      Sets the program name and the parameter list and runs the program on the system.
      void setMessageOption(int messageOption)
      Specifies the option for how many messages should be retrieved.
      void setParameterList(ProgramParameter[] parameterList)
      Sets the list of parameters to pass to the program.
      void setProgram(java.lang.String program)
      Sets the path name of the program.
      void setProgram(java.lang.String program, ProgramParameter[] parameterList)
      Sets the path name of the program and the parameter list.
      void setSystem(AS400 system)
      Sets the system to run the program.
      void setThreadSafe(boolean threadSafe)
      Specifies whether or not the program should be assumed thread-safe.
      void setTimeOut(int timeOut)
      Sets a valid time to run the program
      void suggestThreadsafe()
      Specifies that the called program should be assumed to be thread-safe.
      java.lang.String toString()
      Returns the string representation of this program call object.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Constructor Detail

      • ProgramCall

        public ProgramCall()
        Constructs a ProgramCall object. The system, program, and parameters must be set before using any method requiring a connection to the system.
      • ProgramCall

        public ProgramCall(AS400 system)
        Constructs a ProgramCall object. It uses the specified system. The program and parameters must be provided later.
        Parameters:
        system - The system on which to run the program.
      • ProgramCall

        public ProgramCall(AS400 system,
                   java.lang.String program,
                   ProgramParameter[] parameterList)
        Constructs a program call object. It uses the specified system, program name, and parameter list.
        Parameters:
        system - The system on which to run the program.
        program - The program name as a fully qualified path name in the library file system. The library and program name must each be 10 characters or less.
        parameterList - A list of up to 35 parameters with which to run the program.
    >
    • Method Detail

      • setTimeOut

        public void setTimeOut(int timeOut)
        Sets a valid time to run the program
        Parameters:
        timeOut - the valid time in sec
      • getTimeout

        public int getTimeout()
        Gets a valid time
        Returns:
        the valid time in sec
      • isRunning

        public boolean isRunning()
        Check if the program is still running
        Returns:
        true if the program is still running, otherwise return false
      • cancel

        public void cancel()
        End program call if the time exceeds the specified time
      • addActionCompletedListener

        public void addActionCompletedListener(ActionCompletedListener listener)
        Adds an ActionCompletedListener. The specified ActionCompletedListener's actionCompleted method will be called each time a program has run. The ActionCompletedListener object is added to a list of ActionCompletedListeners managed by this ProgramCall. It can be removed with removeActionCompletedListener.
        Parameters:
        listener - The listener object.
      • addParameter

        public void addParameter(ProgramParameter parameter)
                          throws java.beans.PropertyVetoException
        Adds a ProgramParameter to the parameter list.
        Parameters:
        parameter - The ProgramParameter.
        Throws:
        java.beans.PropertyVetoException - If the change is vetoed.
      • addPropertyChangeListener

        public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
        Adds a PropertyChangeListener. The specified PropertyChangeListener's propertyChange method will be called each time the value of any bound property is changed. The PropertyChangeListener object is added to a list of PropertyChangeListeners managed by this ProgramCall. It can be removed with removePropertyChangeListener.
        Parameters:
        listener - The listener object.
      • addVetoableChangeListener

        public void addVetoableChangeListener(java.beans.VetoableChangeListener listener)
        Adds a VetoableChangeListener. The specified VetoableChangeListener's vetoableChange method will be called each time the value of any constrained property is changed.
        Parameters:
        listener - The listener object.
      • getMessageList

        public AS400Message[] getMessageList()
        Returns the list of messages returned from running the program. It will return an empty list if the program has not been run yet or if there are no messages.
        Returns:
        The array of messages returned by the program.
      • getParameterList

        public ProgramParameter[] getParameterList()
        Returns the list of parameters. It will return an empty list if not previously set.
        Returns:
        The list of parameters.
      • getProgram

        public java.lang.String getProgram()
        Returns the integrated file system pathname for the program. It will return an empty string ("") if not previously set.
        Returns:
        The integrated file system pathname for the program.
      • getServerJob

        public Job getServerJob()
                         throws AS400SecurityException,
                                ErrorCompletingRequestException,
                                java.io.IOException,
                                java.lang.InterruptedException
        Returns a Job object which represents the server job in which the program will be run. The information contained in the Job object is invalidated by AS400.disconnectService() or AS400.disconnectAllServices().
        Typical uses include:
        (1) before run() to identify the job before calling the program;
        (2) after run() to see what job the program ran under (to identify the job log, for example).

        Note: This method is not supported in the Toolbox proxy environment.

        Returns:
        The job in which the program will be run.
        Throws:
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.io.IOException - If an error occurs while communicating with the system.
        java.lang.InterruptedException - If this thread is interrupted.
      • getSystem

        public AS400 getSystem()
        Returns the system on which the program is to be run.
        Returns:
        The system on which the program is to be run. If the system has not been set, null is returned.
      • getSystemThread

        public java.lang.Thread getSystemThread()
                                         throws AS400SecurityException,
                                                java.io.IOException
        Returns the thread on which the program would be run, if it were to be called on-thread. Returns null if either:
        • The client is communicating with the system through sockets.
        • The program has not been marked as thread safe.
        Returns:
        The thread on which the program would be run.
        Throws:
        AS400SecurityException - If a security or authority error occurs.
        java.io.IOException - If an error occurs while communicating with the system.
      • isStayOnThread

        public boolean isStayOnThread()
                               throws AS400SecurityException,
                                      ErrorCompletingRequestException,
                                      java.io.IOException,
                                      java.lang.InterruptedException
        Indicates whether or not the program will actually get run on the current thread.
        Note: If the program is run on-thread, it will run in a different job than if it were run off-thread.
        Returns:
        true if the program will be run on the current thread; false otherwise.
        Throws:
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.io.IOException - If an error occurs while communicating with the system.
        java.lang.InterruptedException - If this thread is interrupted.
      • isThreadSafe

        public boolean isThreadSafe()
        Deprecated. The name of this method is misleading. Use isStayOnThread() instead.
        Indicates whether or not the program will be assumed thread-safe, according to the settings specified by setThreadSafe() or the com.ibm.as400.access.ProgramCall.threadSafe property.
        Note: If the program is run on-thread, it will run in a different job than if it were run off-thread.
        Returns:
        true if the program will be assumed thread-safe; false otherwise.
      • removeActionCompletedListener

        public void removeActionCompletedListener(ActionCompletedListener listener)
        Removes the ActionCompletedListener. If the ActionCompletedListener is not on the list, nothing is done.
        Parameters:
        listener - The listener object.
      • removePropertyChangeListener

        public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
        Removes the PropertyChangeListener. If the PropertyChangeListener is not on the list, nothing is done.
        Parameters:
        listener - The listener object.
      • removeVetoableChangeListener

        public void removeVetoableChangeListener(java.beans.VetoableChangeListener listener)
        Removes the VetoableChangeListener. If the VetoableChangeListener is not on the list, nothing is done.
        Parameters:
        listener - The listener object.
      • run

        public boolean run(java.lang.String program,
                  ProgramParameter[] parameterList)
                    throws AS400SecurityException,
                           ErrorCompletingRequestException,
                           java.io.IOException,
                           java.lang.InterruptedException,
                           ObjectDoesNotExistException,
                           java.beans.PropertyVetoException
        Sets the program name and the parameter list and runs the program on the system.
        Parameters:
        program - The fully qualified integrated file system path name to the program. The library and program name must each be 10 characters or less.
        parameterList - The list of parameters with which to run the program.
        Returns:
        true if program ran successfully, false otherwise.
        Throws:
        AS400SecurityException - If a security or authority error occurs.
        ErrorCompletingRequestException - If an error occurs before the request is completed.
        java.io.IOException - If an error occurs while communicating with the system.
        java.lang.InterruptedException - If this thread is interrupted.
        ObjectDoesNotExistException - If the object does not exist on the system.
        java.beans.PropertyVetoException - If a change is vetoed.
      • setParameterList

        public void setParameterList(ProgramParameter[] parameterList)
                              throws java.beans.PropertyVetoException
        Sets the list of parameters to pass to the program.
        Parameters:
        parameterList - A list of up to 35 parameters with which to run the program.
        Throws:
        java.beans.PropertyVetoException - If a change is vetoed.
      • setProgram

        public void setProgram(java.lang.String program,
                      ProgramParameter[] parameterList)
                        throws java.beans.PropertyVetoException
        Sets the path name of the program and the parameter list.
        Parameters:
        program - The fully qualified integrated file system path name to the program. The library and program name must each be 10 characters or less.
        parameterList - A list of up to 35 parameters with which to run the program.
        Throws:
        java.beans.PropertyVetoException - If a change is vetoed.
      • setProgram

        public void setProgram(java.lang.String program)
                        throws java.beans.PropertyVetoException
        Sets the path name of the program.
        Parameters:
        program - The fully qualified integrated file system path name to the program. The library and program name must each be 10 characters or less.
        Throws:
        java.beans.PropertyVetoException - If the change is vetoed.
      • setMessageOption

        public void setMessageOption(int messageOption)
        Specifies the option for how many messages should be retrieved. By default, to preserve compatability, only the messages sent to the program caller and only up to ten messages are retrieved. This property will only take affect on systems that support the new option.
        Parameters:
        messageOption - A constant indicating how many messages to retrieve. Valid values are:
        • AS400Message.MESSAGE_OPTION_UP_TO_10
        • AS400Message.MESSAGE_OPTION_NONE
        • AS400Message.MESSAGE_OPTION_ALL
      • setSystem

        public void setSystem(AS400 system)
                       throws java.beans.PropertyVetoException
        Sets the system to run the program. The system cannot be changed once a connection is made to the system.
        Parameters:
        system - The system on which to run the program.
        Throws:
        java.beans.PropertyVetoException - If the change is vetoed.
      • setThreadSafe

        public void setThreadSafe(boolean threadSafe)
        Specifies whether or not the program should be assumed thread-safe. The default is false.
        Note: This method has no effect if the Java application is running remotely, that is, is not running "natively" on an IBM i system. When running remotely, the Toolbox submits all program calls through the Remote Command Host Server, regardless of the value of the threadSafe attribute.
        Note: This method does not modify the actual program object on the system.
        Note: If the program is run on-thread, it will run in a different job than if it were run off-thread.
        Parameters:
        threadSafe - true if the program should be assumed to be thread-safe; false otherwise.
      • suggestThreadsafe

        public void suggestThreadsafe()
        Specifies that the called program should be assumed to be thread-safe. If the system property com.ibm.as400.access.ProgramCall.threadSafe has been set, this method does nothing.
      • toString

        public java.lang.String toString()
        Returns the string representation of this program call object.
        Overrides:
        toString in class java.lang.Object
        Returns:
        The string representing this program call object.