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

Represents an IBM i command object. This class allows the user to call any non-interactive CL command. Results of the command are returned in a message list.

Note: CommandCall is not designed to return interactive (screen-oriented) results, such as from "WRK..." and "DSP..." commands. The recommended approach in such cases is to identify an equivalent IBM i API or program, and use ProgramCall instead.

The following example demonstrates the use of CommandCall:

    // Work with commands on system 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 system.
    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:

Command, Serialized Form

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.Boolean	THREADSAFE_FALSE Indicates that the command should be assumed to be non-threadsafe.
static java.lang.Boolean	THREADSAFE_LOOKUP Indicates that the command's threadsafety should be looked-up at runtime.
static java.lang.Boolean	THREADSAFE_TRUE Indicates that the command should be assumed to be threadsafe.

Constructor Summary

Constructors

Constructor and Description
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

Methods

Modifier and Type	Method and Description
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() Deprecated. Use getServerJob() instead.
AS400Message[]	getMessageList() Returns the list of messages returned from running the command.
AS400Message	getMessageList(int index) Returns a message returned from running the command.
int	getMessageOption() Returns the option for how many messages will be retrieved.
Job	getServerJob() Returns a Job object which represents the system job in which the command will be run.
AS400	getSystem() Returns the system 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.
int	getThreadsafeIndicator() Returns the value of the "Threadsafe" attribute of the CL command on the system.
boolean	isStayOnThread() Indicates whether or not the command will actually get run on the current thread.
boolean	isThreadSafe() Deprecated. The name of this method is misleading. Use isStayOnThread() or getThreadsafeIndicator() 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 command on the system.
boolean	run(byte[] command) Runs the command on the system.
boolean	run(java.lang.String command) Sets the command and runs it on the system.
void	setCommand(java.lang.String command) Sets the command to run.
void	setMessageOption(int messageOption) Specifies the option for how many messages should be retrieved.
void	setSystem(AS400 system) Sets the system to run the command.
void	setThreadSafe(boolean threadSafe) Specifies whether or not the command should be assumed thread-safe.
void	setThreadSafe(java.lang.Boolean threadSafe) Specifies whether or not the command should be assumed thread-safe.
void	suggestThreadsafe(boolean threadSafe) Specifies whether or not the command should be assumed to be 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

Field Detail

THREADSAFE_FALSE

public static final java.lang.Boolean THREADSAFE_FALSE

Indicates that the command should be assumed to be non-threadsafe.

THREADSAFE_TRUE

public static final java.lang.Boolean THREADSAFE_TRUE

Indicates that the command should be assumed to be threadsafe.

THREADSAFE_LOOKUP

public static final java.lang.Boolean THREADSAFE_LOOKUP

Indicates that the command's threadsafety should be looked-up at runtime. This setting should be used with caution, especially if this CommandCall object will be used to call a sequence of different commands that need to use the same QTEMP library or the same modified LIBLIST.

Constructor Detail

CommandCall

public CommandCall()

Constructs a CommandCall object. The system and the command properties must be set before using any method requiring a connection to the system.

CommandCall

public CommandCall(AS400 system)

Constructs a CommandCall object. It uses the specified system. The command must be set later.

Parameters:

system - The system on which to run 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 system on which to run the command.

command - The command to run on the system. 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 listener object.

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

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

Deprecated. Use getServerJob() instead.

Do not use this method. It is obsolete and will be removed in a future release.

Returns:

RJob

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.

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

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 system 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 system.

java.lang.InterruptedException - If this thread is interrupted.

getSystem

public AS400 getSystem()

Returns the system on which the command is to be run.

Returns:

The system 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,
                                        ErrorCompletingRequestException,
                                        java.io.IOException,
                                        java.lang.InterruptedException

Returns the thread on which the command would be run, if it were to be called on-thread.

Returns:

The thread on which the command would be run. Returns null if either:

• The client is communicating with the system through sockets.
• The command has not been marked as thread safe.

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.

getThreadsafeIndicator

public int getThreadsafeIndicator()
                           throws AS400SecurityException,
                                  ErrorCompletingRequestException,
                                  java.io.IOException,
                                  java.lang.InterruptedException

Returns the value of the "Threadsafe" attribute of the CL command on the system.

Returns:

The value of the command's Threadsafe attribure. Valid values are:

• 0 - The command is not threadsafe and should not be used in a multithreaded job.
• 1 - The command is threadsafe and can be used safely in a multithreaded job.
• 2 - The command is threadsafe under certain conditions. See the documentation for the command to determine the conditions under which the command can be used safely in a multithreaded job.

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.

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.
Note: If the command is run on-thread, it will run in a different job (with different QTEMP library and different job log) than if it were run off-thread.
Note: If the threadsafety behavior is set to THREADSAFE_LOOKUP, then the value returned by this method will depend on the command string that has been specified, in either the constructor or in setCommand().

Returns:

true if the command will be run on the current thread; false otherwise. If the application is not running on IBM i, false is always returned.

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.

See Also:

setThreadSafe(Boolean)

isThreadSafe

public boolean isThreadSafe()
                     throws AS400SecurityException,
                            ErrorCompletingRequestException,
                            java.io.IOException,
                            java.lang.InterruptedException

Deprecated. The name of this method is misleading. Use isStayOnThread() or getThreadsafeIndicator() instead.

Indicates whether or not the command will be assumed thread-safe. The determination is based upon the settings specified by setThreadSafe() or the com.ibm.as400.access.CommandCall.threadSafe property.
Note: If the CL command on the system 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:

• Run the command. Do not send a message.
• Send an informational message and run the command.
• Send an escape message, and do not run the command.

Note: If the command is run on-thread, it will run in a different job (with different QTEMP library and different job log) than if it were run off-thread.

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 system.

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

Runs the command on the system. The command must be set prior to this call.
Note: Interactive (screen-oriented) results are not returned.

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 system.

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 system.
Note: Interactive (screen-oriented) results are not returned.

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 system.

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 system. 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 IBM i format (EBCDIC) before sending it to the system 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 may 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 cannot look up the thread safety of the command, and will assume that the command is not thread-safe. If this command is to be run on-thread when running on the system's JVM, setThreadSafe(true) must be called by the application.
Note: Interactive (screen-oriented) results are not returned.

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 system.

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 system. 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.

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

• MESSAGE_OPTION_UP_TO_10
• MESSAGE_OPTION_NONE
• MESSAGE_OPTION_ALL

setSystem

public void setSystem(AS400 system)
               throws java.beans.PropertyVetoException

Sets the system to run the command. The system cannot be changed once a connection is made to the system.

Parameters:

system - The system 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 false; that is, the command will be assumed to be not thread-safe.
This method is an alternative to setThreadSafe(Boolean). For example, calling setThreadSafe(true) is equivalent to calling setThreadSafe(Boolean.TRUE).
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 command calls through the Remote Command Host Server, regardless of the value of the threadSafe attribute.
Note: This method does not modify the actual command object on the system.
Note: If the command is run on-thread, it will run in a different job (with different QTEMP library and different job log) than if it were run off-thread.

Parameters:

threadSafe - true if the command should be assumed to be thread-safe; false otherwise.

See Also:

setThreadSafe(Boolean)

setThreadSafe

public void setThreadSafe(java.lang.Boolean threadSafe)

Specifies whether or not the command should be assumed thread-safe. If not specified, the default is THREADSAFE_FALSE.
Note: This method has no effect if the Java application is running remotely, that is, is not "natively" on an IBM i system. When running remotely, all command calls are submitted through the Remote Command Host Server, regardless of the value of the threadSafe attribute.
Note: This method does not modify the actual command object on the system.
Note: If the command is run on-thread, it will run in a different job (with different QTEMP library and different job log) than if it were run off-thread.

Parameters:

threadSafe - Valid values are:

• THREADSAFE_TRUE
• THREADSAFE_FALSE
• THREADSAFE_LOOKUP

See Also:

setThreadSafe(boolean), isStayOnThread()

suggestThreadsafe

public void suggestThreadsafe(boolean threadSafe)

Specifies whether or not the command should be assumed to be thread-safe. If the system property com.ibm.as400.access.CommandCall.threadSafe has been set to a value other than "lookup", this method does nothing. This method is typically used in order to suppress runtime lookups of the CL command's "Threadsafe Indicator" attribute.

Parameters:

threadSafe - true if the command should be assumed to be thread-safe; false if the command should be assumed to be not thread-safe.

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.