com.ibm.as400.access
Class ProgramCall

java.lang.Object
  com.ibm.as400.access.ProgramCall

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

ServiceProgramCall

public class ProgramCall
extends Object
implements 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.

See Also:

ProgramParameter, AS400Message, ServiceProgramCall, Serialized Form

Constructor and Description

ProgramCall()
Constructs a ProgramCall object.

ProgramCall(AS400 system)
Constructs a ProgramCall object.

ProgramCall(AS400 system, String program, ProgramParameter[] parameterList)
Constructs a program call object.

Method Summary

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(PropertyChangeListener listener) Adds a PropertyChangeListener.
void	addVetoableChangeListener(VetoableChangeListener listener) Adds a VetoableChangeListener.
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.
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.
Thread	getSystemThread() Returns the thread on which the program would be run, if it were to be called on-thread.
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(PropertyChangeListener listener) Removes the PropertyChangeListener.
void	removeVetoableChangeListener(VetoableChangeListener listener) Removes the VetoableChangeListener.
boolean	run() Runs the program on the system.
boolean	run(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(String program) Sets the path name of the program.
void	setProgram(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	suggestThreadsafe() Specifies that the called program should be assumed to be thread-safe.
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,
                   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

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 PropertyVetoException

Adds a ProgramParameter to the parameter list.

Parameters:

parameter - The ProgramParameter.

Throws:

PropertyVetoException - If the change is vetoed.

addPropertyChangeListener

public void addPropertyChangeListener(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(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 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,
                        IOException,
                        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.

IOException - If an error occurs while communicating with the system.

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 Thread getSystemThread()
                       throws AS400SecurityException,
                              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.

IOException - If an error occurs while communicating with the system.

isStayOnThread

public boolean isStayOnThread()
                       throws AS400SecurityException,
                              ErrorCompletingRequestException,
                              IOException,
                              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.

IOException - If an error occurs while communicating with the system.

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(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(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,
                   IOException,
                   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.

IOException - If an error occurs while communicating with the system.

InterruptedException - If this thread is interrupted.

ObjectDoesNotExistException - If the object does not exist on the system.

run

public boolean run(String program,
                   ProgramParameter[] parameterList)
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   IOException,
                   InterruptedException,
                   ObjectDoesNotExistException,
                   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.

IOException - If an error occurs while communicating with the system.

InterruptedException - If this thread is interrupted.

ObjectDoesNotExistException - If the object does not exist on the system.

PropertyVetoException - If a change is vetoed.

setParameterList

public void setParameterList(ProgramParameter[] parameterList)
                      throws 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:

PropertyVetoException - If a change is vetoed.

setProgram

public void setProgram(String program,
                       ProgramParameter[] parameterList)
                throws 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:

PropertyVetoException - If a change is vetoed.

setProgram

public void setProgram(String program)
                throws 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:

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 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:

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 String toString()

Returns the string representation of this program call object.

Overrides:

toString in class Object

Returns:

The string representing this program call object.