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

Constructor Summary

Constructors
Constructor and Description
`ProgramCall()` Constructs a ProgramCall object.
`ProgramCall(AS400 system)` Constructs a ProgramCall object.
`ProgramCall(AS400 system, java.lang.String program, ProgramParameter[] parameterList)` Constructs a program call object.

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.
  - getMessageOption
```
public int getMessageOption()
```
    Returns the option for how many messages will be retrieved.
    Returns:
    A constant indicating how many messages will be retrieved. Valid values are:
    
    MESSAGE_OPTION_UP_TO_10
    MESSAGE_OPTION_NONE
    MESSAGE_OPTION_ALL
  - 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()
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   java.io.IOException,
                   java.lang.InterruptedException,
                   ObjectDoesNotExistException
```
    Runs the program on the system. The program and parameter list need to be set prior to this call.
    
    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.
  - 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.

Methods inherited from class java.lang.Object

ProgramCall

ProgramCall

ProgramCall

setTimeOut

getTimeout

isRunning

cancel

addActionCompletedListener

addParameter

addPropertyChangeListener

addVetoableChangeListener

getMessageList

getMessageOption

getParameterList

getProgram

getServerJob

getSystem

getSystemThread

isStayOnThread

isThreadSafe

removeActionCompletedListener

removePropertyChangeListener

removeVetoableChangeListener

run

run

setParameterList

setProgram

setProgram

setMessageOption

setSystem

setThreadSafe

suggestThreadsafe

toString