com.ibm.as400.access
Class CommandCall

java.lang.Object
  |
  +--com.ibm.as400.access.CommandCall

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

The CommandCall class represents an AS/400 command object. This class allows the user to call an AS/400 CL command. Results of the command are returned in a message list.

The following example demonstrates the use of CommandCall:

// Work with commands on system "Hal"
AS400 system = new AS400("Hal");
CommandCall command = new CommandCall(system);
try
{
// Run the command "CRTLIB FRED"
if (command.run("CRTLIB FRED") != true)
{
// Note that there was an error
System.out.println("Program failed!");
}
// Show the messages (returned whether or not there was an error)
AS400Message[] messagelist = command.getMessageList();
for (int i = 0; i < messagelist.length; ++i)
{
// Show each message
System.out.println(messagelist[i].getText());
}
}
catch (Exception e)
{
System.out.println("Command " + command.getCommand() + " did not run!");
}
// done with the system
system.disconnectAllServices();

NOTE: When getting the AS400Message list from commands, 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 (command.run("myCmd") != true)
{
// Show messages.
AS400Message[] messageList = command.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:
AS400Message, MessageFile, Serialized Form

Constructor Summary
CommandCall()
          Constructs a CommandCall object.
CommandCall(AS400 system)
          Constructs a CommandCall object.
CommandCall(AS400 system, java.lang.String command)
          Constructs a CommandCall object.
 
Method Summary
 void addActionCompletedListener(ActionCompletedListener listener)
          Adds an ActionCompletedListener.
 void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
          Adds a PropertyChangeListener.
 void addVetoableChangeListener(java.beans.VetoableChangeListener listener)
          Adds a VetoableChangeListener.
 java.lang.String getCommand()
          Returns the command to run.
 RJob getJob()
          Returns an RJob object which represents the AS/400 job in which the command will be run.
 AS400Message[] getMessageList()
          Returns the list of AS/400 messages returned from running the command.
 AS400Message getMessageList(int index)
          Returns an AS/400 message returned from running the command.
 AS400 getSystem()
          Returns the AS/400 on which the command is to be run.
 java.lang.Thread getSystemThread()
          Returns the AS/400 thread on which the command would be run, if it were to be called on-thread.
 boolean isStayOnThread()
          Indicates whether or not the AS/400 command will actually get run on the current thread.
 boolean isThreadSafe()
          Indicates whether or not the AS/400 command will be assumed thread-safe, according to the settings specified by setThreadSafe() or the com.ibm.as400.access.CommandCall.threadSafe property.
 void removeActionCompletedListener(ActionCompletedListener listener)
          Removes this ActionCompletedListener.
 void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
          Removes this PropertyChangeListener.
 void removeVetoableChangeListener(java.beans.VetoableChangeListener listener)
          Removes this VetoableChangeListener.
 boolean run()
          Runs the command on the AS/400.
 boolean run(byte[] command)
          Runs the command on the AS/400.
 boolean run(java.lang.String command)
          Sets the command string and runs it on the AS/400.
 void setCommand(java.lang.String command)
          Sets the command to run.
 void setSystem(AS400 system)
          Sets the AS/400 to run the command.
 void setThreadSafe(boolean threadSafe)
          Specifies whether or not the command should be assumed thread-safe.
 java.lang.String toString()
          Returns the string representation of this command call object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

CommandCall

public CommandCall()
Constructs a CommandCall object. The system and the command string must be set later.

CommandCall

public CommandCall(AS400 system)
Constructs a CommandCall object. It uses the specified system. The command string must be set later.
Parameters:
system - The AS/400 on which to issue the command.

CommandCall

public CommandCall(AS400 system,
                   java.lang.String command)
Constructs a CommandCall object. It uses the specified system and command.
Parameters:
system - The AS/400 on which to issue the command.
command - The command to run on the AS/400. If the command is not library qualified, the library list will be used to find the command.
Method Detail

addActionCompletedListener

public void addActionCompletedListener(ActionCompletedListener listener)
Adds an ActionCompletedListener. The specified ActionCompletedListeners actionCompleted method will be called each time a command has run. The ActionCompletedListener object is added to a list of ActionCompletedListeners managed by this CommandCall; it can be removed with removeActionCompletedListener.
Parameters:
listener - The ActionCompletedListener.
See Also:
removeActionCompletedListener(com.ibm.as400.access.ActionCompletedListener)

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 CommandCall; 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)

getCommand

public java.lang.String getCommand()
Returns the command to run. It will return an empty string ("") if the command has not been previously set by the constructor, setCommand, or run.
Returns:
The command to run.

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 command 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 command;
(2) after run() to see what job the command ran under (to identify the job log, for example).
Returns:
The job in which the command 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.
ServerStartupException - If the AS/400 server cannot be started.
java.net.UnknownHostException - If the AS/400 system cannot be located.

getMessageList

public AS400Message[] getMessageList()
Returns the list of AS/400 messages returned from running the command. It will return an empty list if the command has not been run yet.
Returns:
The array of messages returned by the AS/400 for the command.

getMessageList

public AS400Message getMessageList(int index)
Returns an AS/400 message returned from running the command.
Parameters:
index - The index into the list of messages returned by the AS/400 for the command. It must be greater than or equal to zero and less than the number of messages in the list.
Returns:
The message at the requested index returned by the AS/400 for the command.

getSystem

public AS400 getSystem()
Returns the AS/400 on which the command is to be run.
Returns:
The AS/400 on which the command 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 command would be run, if it were to be called on-thread. Returns null if either:
Returns:
The AS/400 thread on which the command 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 command will actually get run on the current thread.
Returns:
true if the command 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.
ServerStartupException - If the AS/400 server cannot be started.
java.net.UnknownHostException - If the AS/400 system cannot be located.
See Also:
isThreadSafe()

isThreadSafe

public boolean isThreadSafe()
                     throws AS400SecurityException,
                            ErrorCompletingRequestException,
                            java.io.IOException,
                            java.lang.InterruptedException
Indicates whether or not the AS/400 command will be assumed thread-safe, according to the settings specified by setThreadSafe() or the com.ibm.as400.access.CommandCall.threadSafe property.
Note: If the CL command on the AS/400 is not actually threadsafe (as indicated by its "threadsafe indicator" attribute), then the results of attempting to run the command on-thread will depend on the command's "multithreaded job action" attribute, in combination with the setting of system value QMLTTHDACN ("Multithreaded job action"). Possible results are:
Returns:
true if the command will be assumed thread-safe; 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.
ServerStartupException - If the AS/400 server cannot be started.
java.net.UnknownHostException - If the AS/400 system cannot be located.
See Also:
isStayOnThread()

removeActionCompletedListener

public void removeActionCompletedListener(ActionCompletedListener listener)
Removes this 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 this 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 this 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
Runs the command on the AS/400. The command must be set prior to this call.
Returns:
true if command is successful; 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.
ServerStartupException - If the AS/400 server cannot be started.
java.net.UnknownHostException - If the AS/400 system cannot be located.

run

public boolean run(java.lang.String command)
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   java.io.IOException,
                   java.lang.InterruptedException,
                   java.beans.PropertyVetoException
Sets the command string and runs it on the AS/400.
Parameters:
command - The command to run on the AS/400. If the command is not library qualified, the library list will be used to find the command.
Returns:
true if command is successful; 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.
java.beans.PropertyVetoException - If the change is vetoed.
ServerStartupException - If the AS/400 server cannot be started.
java.net.UnknownHostException - If the AS/400 system cannot be located.

run

public boolean run(byte[] command)
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   java.io.IOException,
                   java.lang.InterruptedException,
                   java.beans.PropertyVetoException
Runs the command on the AS/400. This method takes the command to run as a byte array instead of a String. The most common use of CommandCall is to supply the command to run as a String and let the Toolbox convert the string to AS/400 format (EBCDIC) before sending it to the AS/400 for processing. Use this method if the default conversion of the command string to EBCDIC is not correct. In certain cases, especially bi-directional languages, the Toolbox conversion is not be correct. In this case the application can construct their own command and supply it to CommandCall as a byte array.

Unlike the run method that takes a string, this method will not look up the thread safety of the command. If this command is to be run on-thread when running on the AS/400's JVM, setThreadSafe(true) must be called by the application.

Parameters:
command - The command to run on the AS/400.
Returns:
true if command is successful; 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.
java.beans.PropertyVetoException - If the change is vetoed.
ServerStartupException - If the AS/400 server cannot be started.
java.net.UnknownHostException - If the AS/400 system cannot be located.

setCommand

public void setCommand(java.lang.String command)
                throws java.beans.PropertyVetoException
Sets the command to run.
Parameters:
command - The command to run on the AS/400. If the command is not library qualified, the library list will be used to find the command.
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 command. The system cannot be changed once a connection is made to the server.
Parameters:
system - The AS/400 to run the command.
Throws:
java.beans.PropertyVetoException - If the change is vetoed.

setThreadSafe

public void setThreadSafe(boolean threadSafe)
Specifies whether or not the command should be assumed thread-safe. If not specified, the default is the command's actual "threadsafe" attribute on the AS/400. The thread-safety lookup is a run-time check, so it will affect performance. To be as fast as possible, we recommend setting this attribute, to avoid the run-time lookup.
Note: This method does not modify the actual command object on the AS/400.
Parameters:
threadSafe - true if the command 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 command call object.
Overrides:
toString in class java.lang.Object
Returns:
The string representing this command call object.