com.ibm.as400.access
Class CommandCall

java.lang.Object
  |
  +--com.ibm.as400.access.CommandCall
All Implemented Interfaces:
java.io.Serializable

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

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

The following example demonstrates the use of CommandCall:

    // Work with commands on server named "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("Command 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() + " issued an exception!");
        e.printStackTrace();
    }
    // Done with the server.
    system.disconnectService(AS400.COMMAND);

NOTE: When getting the message list from commands, users no longer have to create a MessageFile to obtain the message 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:
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 server job in which the command will be run.
 AS400Message[] getMessageList()
          Returns the list of messages returned from running the command.
 AS400Message getMessageList(int index)
          Returns a message returned from running the command.
 Job getServerJob()
          Returns a Job object which represents the server job in which the command will be run.
 AS400 getSystem()
          Returns the server on which the command is to be run.
 java.lang.Thread getSystemThread()
          Returns the thread on which the command would be run, if it were to be called on-thread.
 boolean isStayOnThread()
          Indicates whether or not the command will actually get run on the current thread.
 boolean isThreadSafe()
          Indicates whether or not the 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 the ActionCompletedListener.
 void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
          Removes the PropertyChangeListener.
 void removeVetoableChangeListener(java.beans.VetoableChangeListener listener)
          Removes the VetoableChangeListener.
 boolean run()
          Runs the command on the server.
 boolean run(byte[] command)
          Runs the command on the server.
 boolean run(java.lang.String command)
          Sets the command and runs it on the server.
 void setCommand(java.lang.String command)
          Sets the command to run.
 void setSystem(AS400 system)
          Sets the server 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 server and the command must be set later.

CommandCall

public CommandCall(AS400 system)
Constructs a CommandCall object. It uses the specified server. The command must be set later.
Parameters:
system - The server on which to run the command.

CommandCall

public CommandCall(AS400 system,
                   java.lang.String command)
Constructs a CommandCall object. It uses the specified server and command.
Parameters:
system - The server on which to run the command.
command - The command to run on the server. 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 ActionCompletedListener's 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.

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 CommandCall. It can be removed with removePropertyChangeListener.
Parameters:
listener - The PropertyChangeListener.

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 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.
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 server 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).

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

Returns:
The job in which the command 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 server.
java.lang.InterruptedException - If this thread is interrupted.
See Also:
getServerJob()

getMessageList

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

getMessageList

public AS400Message getMessageList(int index)
Returns a message returned from running the command.
Parameters:
index - The index into the list of messages returned by 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 command.

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 command 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 command;
(2) after run() to see what job the command 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 command 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 server.
java.lang.InterruptedException - If this thread is interrupted.
See Also:
getJob()

getSystem

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

getSystemThread

public java.lang.Thread getSystemThread()
                                 throws AS400SecurityException,
                                        java.io.IOException
Returns the thread on which the command would be run, if it were to be called on-thread. Returns null if either:
Returns:
The 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 server.

isStayOnThread

public boolean isStayOnThread()
                       throws AS400SecurityException,
                              ErrorCompletingRequestException,
                              java.io.IOException,
                              java.lang.InterruptedException
Indicates whether or not the 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.
ErrorCompletingRequestException - If an error occurs before the request is completed.
java.io.IOException - If an error occurs while communicating with the server.
java.lang.InterruptedException - If this thread is interrupted.

isThreadSafe

public boolean isThreadSafe()
                     throws AS400SecurityException,
                            ErrorCompletingRequestException,
                            java.io.IOException,
                            java.lang.InterruptedException
Indicates whether or not the 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 server 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.
ErrorCompletingRequestException - If an error occurs before the request is completed.
java.io.IOException - If an error occurs while communicating with the server.
java.lang.InterruptedException - If this thread is interrupted.

removeActionCompletedListener

public void removeActionCompletedListener(ActionCompletedListener listener)
Removes the ActionCompletedListener. If the ActionCompletedListener is not on the list, nothing is done.
Parameters:
listener - The 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.

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.

run

public boolean run()
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   java.io.IOException,
                   java.lang.InterruptedException
Runs the command on the server. 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.
ErrorCompletingRequestException - If an error occurs before the request is completed.
java.io.IOException - If an error occurs while communicating with the server.
java.lang.InterruptedException - If this thread is interrupted.

run

public boolean run(java.lang.String command)
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   java.io.IOException,
                   java.lang.InterruptedException,
                   java.beans.PropertyVetoException
Sets the command and runs it on the server.
Parameters:
command - The command to run. 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.
ErrorCompletingRequestException - If an error occurs before the request is completed.
java.io.IOException - If an error occurs while communicating with the server.
java.lang.InterruptedException - If this thread is interrupted.
java.beans.PropertyVetoException - If the change is vetoed.

run

public boolean run(byte[] command)
            throws AS400SecurityException,
                   ErrorCompletingRequestException,
                   java.io.IOException,
                   java.lang.InterruptedException,
                   java.beans.PropertyVetoException
Runs the command on the server. 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 server format (EBCDIC) before sending it to the server for processing. Use this method if the default conversion of the command 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 server's JVM, setThreadSafe(true) must be called by the application.

Parameters:
command - The command to run.
Returns:
true if command is successful; 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 server.
java.lang.InterruptedException - If this thread is interrupted.
java.beans.PropertyVetoException - If the change is vetoed.

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 server. 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 server to run the command. The server cannot be changed once a connection is made to the server.
Parameters:
system - The server on which 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 server. 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 server.
Parameters:
threadSafe - true if the command should be assumed to be thread-safe; false otherwise.

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.