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