com.ibm.as400.access
Class ProgramCall

java.lang.Object
  |
  +--com.ibm.as400.access.ProgramCall
Direct Known Subclasses:
ServiceProgramCall

public class ProgramCall
extends java.lang.Object
implements java.io.Serializable

The ProgramCall class allows a user to call an AS/400 program, pass parameters to it (input and output), and access data returned in the output parameters after the program runs. Use ProgramCall to call AS/400 programs. To call AS/400 service programs, use ServiceProgramCall.

The following example demonstrates the use of Program Call:

// Call programs on system "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 parmeter is to get the answer, up to 50 bytes long.
parameterList[1] = new ProgramParameter(50);
// Third parmeter 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() + " did not run!");
}
// 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());
}
}

See Also:
ProgramParameter, AS400Message, ServiceProgramCall, Serialized Form

Constructor Summary
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
 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.
 RJob getJob()
          Returns an RJob object which represents the AS/400 job in which the program will be run.
 AS400Message[] getMessageList()
          Returns the list of AS/400 messages returned from running the program.
 ProgramParameter[] getParameterList()
          Returns the list of parameters.
 java.lang.String getProgram()
          Returns the integrated file system pathname for the program.
 AS400 getSystem()
          Returns the AS/400 on which the program is to be run.
 java.lang.Thread getSystemThread()
          Returns the AS/400 thread on which the program would be run, if it were to be called on-thread.
 boolean isStayOnThread()
          Indicates whether or not the AS/400 program will actually get run on the current thread.
 boolean isThreadSafe()
          Indicates whether or not the AS/400 program will be assumed thread-safe, according to the settings specified by setThreadSafe() or the com.ibm.as400.access.ProgramCall.threadSafe property.
 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 AS/400.
 boolean run(java.lang.String program, ProgramParameter[] parameterList)
          Sets the program name and the parameter list and runs the program on the AS/400.
 void setParameterList(ProgramParameter[] parameterList)
          Sets the list of parameters to pass to the AS/400 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 AS/400 to run the program.
 void setThreadSafe(boolean threadSafe)
          Specifies whether or not the program should be assumed 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 provided later.

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 AS/400 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 AS/400 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

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 ActionCompletedListener.
See Also:
removeActionCompletedListener(com.ibm.as400.access.ActionCompletedListener)

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 PropertyChangeListeners propertyChange method will be called each time the value of any bound property is changed. The PropertyListener object is added to a list of PropertyChangeListeners managed by this ProgramCall, it can be removed with removePropertyChangeListener.
Parameters:
listener - The PropertyChangeListener.
See Also:
removePropertyChangeListener(java.beans.PropertyChangeListener)

addVetoableChangeListener

public void addVetoableChangeListener(java.beans.VetoableChangeListener listener)
Adds a VetoableChangeListener. The specified VetoableChangeListeners vetoableChange method will be called each time the value of any constrained property is changed.
Parameters:
listener - The VetoableChangeListener.
See Also:
removeVetoableChangeListener(java.beans.VetoableChangeListener)

getJob

public RJob getJob()
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   java.io.IOException,
                   java.lang.InterruptedException
Returns an RJob object which represents the AS/400 job in which the program will be run. The information contained in the RJob 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).
Returns:
The job in which the program will be run.
Throws:
AS400SecurityException - If a security or authority error occurs.
ConnectionDroppedException - If the connection is dropped unexpectedly.
ErrorCompletingRequestException - If an error occurs before the request is completed.
java.io.IOException - If an error occurs while communicating with the AS/400.
java.lang.InterruptedException - If this thread is interrupted.

getMessageList

public AS400Message[] getMessageList()
Returns the list of AS/400 messages returned from running the program. It will return an empty list if the program has not been run yet.
Returns:
The array of messages returned by the AS/400 for 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.

getSystem

public AS400 getSystem()
Returns the AS/400 on which the program is to be run.
Returns:
The AS/400 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 AS/400 thread on which the program would be run, if it were to be called on-thread. Returns null if either:
Returns:
The AS/400 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 AS/400.

isStayOnThread

public boolean isStayOnThread()
                       throws AS400SecurityException,
                              ErrorCompletingRequestException,
                              java.io.IOException,
                              java.lang.InterruptedException
Indicates whether or not the AS/400 program will actually get run on the current thread.
Returns:
true if the program will be run on the current thread; false otherwise.
Throws:
AS400SecurityException - If a security or authority error occurs.
ConnectionDroppedException - If the connection is dropped unexpectedly.
ErrorCompletingRequestException - If an error occurs before the request is completed.
java.io.IOException - If an error occurs while communicating with the AS/400.
java.lang.InterruptedException - If this thread is interrupted.
See Also:
isThreadSafe()

isThreadSafe

public boolean isThreadSafe()
Indicates whether or not the AS/400 program will be assumed thread-safe, according to the settings specified by setThreadSafe() or the com.ibm.as400.access.ProgramCall.threadSafe property.
Returns:
true if the program will be assumed thread-safe; false otherwise.
See Also:
isStayOnThread()

removeActionCompletedListener

public void removeActionCompletedListener(ActionCompletedListener listener)
Removes the ActionCompletedListener. If the ActionCompletedListener is not on the list, nothing is done.
Parameters:
listener - The ActionCompletedListener.
See Also:
addActionCompletedListener(com.ibm.as400.access.ActionCompletedListener)

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 PropertyChangeListener.
See Also:
addPropertyChangeListener(java.beans.PropertyChangeListener)

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 VetoableChangeListener.
See Also:
addVetoableChangeListener(java.beans.VetoableChangeListener)

run

public boolean run()
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   java.io.IOException,
                   java.lang.InterruptedException,
                   ObjectDoesNotExistException
Runs the program on the AS/400. 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.
ConnectionDroppedException - If the connection is dropped unexpectedly.
ErrorCompletingRequestException - If an error occurs before the request is completed.
java.io.IOException - If an error occurs while communicating with the AS/400.
java.lang.InterruptedException - If this thread is interrupted.
ObjectDoesNotExistException - If the AS/400 object does not exist.

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 AS/400.
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.
ConnectionDroppedException - If the connection is dropped unexpectedly.
ErrorCompletingRequestException - If an error occurs before the request is completed.
java.io.IOException - If an error occurs while communicating with the AS/400.
java.lang.InterruptedException - If this thread is interrupted.
ObjectDoesNotExistException - If the AS/400 object does not exist.
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 AS/400 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.

setSystem

public void setSystem(AS400 system)
               throws java.beans.PropertyVetoException
Sets the AS/400 to run the program.
Parameters:
system - The AS/400 on which to run the program. The system cannot be changed once a connection is made to the server.
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 does not modify the actual program object on the AS/400.
Parameters:
threadSafe - true if the program should be assumed to be thread-safe; false otherwise.
See Also:
isThreadSafe(), isStayOnThread()

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.