Package com.ibm.di.fc.remotecmdlnfc

Class RemoteCmdLineFC

  • All Implemented Interfaces:
    FunctionInterface, VersionInfoInterface
    public class RemoteCmdLineFC
extends Function

    TDI Remote Command Line Function Component.

    This function component (FC) provides the ability to execute a specified command on a remote machine.

    This FC establishes connections with and invokes commands on remote machines using the IBM Remote Execution and Access toolkit. To use this function component you must have the Remote Command Line FC (with its included jar files) installed correctly on your local machine. The remote machine you wish to execute commands on must have at least one of the following connection protocols configured and running:

    • RSH
    • REXEC
    • SSH
    • A windows connection protocol such as SMB,CIFS,DCE-RPC

    Configuration is accomplished by setting logon parameters for client connections to the specified remote machine (target) where the command is to be executed. See initialize(java.lang.Object) for more details on how to initialize.

    initialize(java.lang.Object) must be the first operation called in this class.
    perform(java.lang.Object) can then be called one or more times.
    terminate() must be called to allow connection cleanup before the class is destroyed.

    The following configuration parameters are available and should be set prior to calling initialize(java.lang.Object). These values can be set through script by setting the available parameter or on the configurable TDI GUI interface for the FC.

    Configuration Item Available Parameter
    Hostname PARAM_CONFIG_HOST
    Remote User Name PARAM_CONFIG_USER
    User Password PARAM_CONFIG_PASSWD
    Connection Protocol PARAM_CONFIG_CONNTYPE
    Path to Keystore PARAM_CONFIG_KEYSTORE
    Passphrase PARAM_CONFIG_PASSPHRASE
    Connection Port PARAM_CONFIG_PORT
    Timeout Duration (ms) PARAM_CONFIG_TIMEOUT
    Command to Execute PARAM_CONFIG_COMMAND
    Local Path to Stdin Source File PARAM_CONFIG_STDIN_SOURCE
    Remote Path to Stdin Destination File PARAM_CONFIG_STDIN_DESTN

    Not all of the configuration parameters must be provided as described above. Three of the configuration parameters can alternatively be provided as attributes in the supplied TDI Entry object. The Entry object is supplied as a parameter to the FC perform(java.lang.Object) method.

    Configuration Item Available Attribute
    Command to Execute PARAM_INPUT
    Local Path to Stdin Source File PARAM_STDIN_SRC
    Remote Path to Stdin Destination File PARAM_STDIN_DEST

    The value provided within the TDI Entry object will have precedence over any value that may have been supplied as a configuration parameter on the GUI. For instance, if a value is provided for the command both on the GUI and as an attribute called PARAM_INPUT in the Entry object then the value configured on the GUI will be disregarded.

    Using the FC
    It can be placed in an assembly line or invoked directly from script. It is the callers' responsibility to check the returned Entry object for any errors that may have resulted from invoking the remote command.
    The following return attributes are available in the Entry object returned by the FC after the perform(java.lang.Object) method has been executed:

    Returned Information Available Attribute
    Standard Output PARAM_STD_OUTPUT
    Standard Error PARAM_STD_ERROR
    Return Code PARAM_RETURN_CODE

    The connection protocol (PARAM_CONFIG_CONNTYP) to be used when establishing a connection:
    • RSH
    • REXEC
    • SSH
    • WIN
    • ANY

    Note that the 'WIN' option will allow you to connect to a Windows host running any of the following protocols: SMB,CIFS or DCE-RPC.


    The FC can be invoked directly from script. As an example the following code can be used to invoke an remote command from JavaScript using the XML string style:

    var fc = system.getFunction("ibmdi.RemoteCmdLineFC");
    var response;
    fc.setParam(fc.PARAM_CONFIG_HOST, "rhat3");
    fc.setParam(fc.PARAM_CONFIG_USER, "SMITH");
    fc.setParam(fc.PARAM_CONFIG_PASSWD, "PASSWORD");
    fc.setParam(fc.PARAM_CONFIG_CONNTYPE, "SSH");
    fc.initialize(null);
    //Create an entry object with an input attribute containing the command to execute
    //Alternatively, the command can be specifed as the value of PARAM_CONFIG_COMMAND.
    var myEntry = system.newEntry();
    myEntry.setAttribute(fc.PARAM_INPUT, "ifconfig");
    myEntry = fc.perform(myEntry);
    var output = myEntry.getAttribute(fc.PARAM_STD_OUTPUT);
    response = output.getValue(0);
    fc.terminate();

    Note that configuration parameters must be set before initialize(java.lang.Object) is called, and terminate() should be called to cleanup.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected java.lang.String[] cmdArgs
      The command arguments to be appended.
      protected java.lang.String cmdArgsDelim
      The command arguments delimiter character.
      protected java.lang.String cmdToExecute
      The command that is to be executed.
      protected CmdLineExecutor executor
      The executor object that connects to the appropriate machine to execute the command.
      protected boolean initialized
      keep track of whether the fc has been initialized
      protected LogProxy logproxy
      The way to perform logging.
      static java.lang.String PARAM_ARGS
      The name of the entry attribute containing the command arguments.
      static java.lang.String PARAM_ARGS_DELIM
      The name of the entry attribute specifing the command argument delimiter.
      protected java.lang.String[] PARAM_BOOL_CONFIG_OPTIONS
      This array stores the names of the TDI GUI boolean parameters that can be configured (excluding those that may be set as attributes in the TDI input Entry).
      static java.lang.String PARAM_CONFIG_AS400_PROXY
      Proxy to be used if required for AS400 connection
      static java.lang.String PARAM_CONFIG_AS400_RUNPROG
      Secondary mechanism for executing AS400 Programs
      static java.lang.String PARAM_CONFIG_AS400_SSL
      Enable or disable SSL over an AS400 connection
      static java.lang.String PARAM_CONFIG_AS400CMDARGSENC
      Character Encoding for AS400 Program cmdArgs
      static java.lang.String PARAM_CONFIG_COMMAND
      Command to execute on target
      static java.lang.String PARAM_CONFIG_CONNTYPE
      The connection type string.
      static java.lang.String PARAM_CONFIG_HOST
      Hostname of Remote Machine (target)
      static java.lang.String PARAM_CONFIG_INITIAL_TIMEOUT
      Timeout parameter of the connection
      static java.lang.String PARAM_CONFIG_KEYSTORE
      Path to the local keystore to be used when connecting to the remote machine using the SSH protocol
      static java.lang.String PARAM_CONFIG_PASSPHRASE
      The passphrase for the keystore
      static java.lang.String PARAM_CONFIG_PASSWD
      User password to authenticate to the target
      static java.lang.String PARAM_CONFIG_PORT
      The port to be used when establishing connection with target
      static java.lang.String PARAM_CONFIG_RXA_LOG
      Enable or disable RXA internal logging
      static java.lang.String PARAM_CONFIG_STDIN_DESTN
      The remote path to the standard input destination file
      static java.lang.String PARAM_CONFIG_STDIN_SOURCE
      The local path to the standard input source file
      static java.lang.String PARAM_CONFIG_TIMEOUT
      Timeout duration for executing the command (ms)
      static java.lang.String PARAM_CONFIG_USER
      The username to be used when connecting to target
      static java.lang.String PARAM_HANDLE_TEXT_FILE
      Parameter to handle as text file
      static java.lang.String PARAM_INPUT
      The name of the entry attribute containing the command to be executed on the target.
      protected java.lang.String[] PARAM_INT_CONFIG_OPTIONS
      This array stores the names of the TDI GUI int parameters that can be configured.
      static java.lang.String PARAM_RETURN_CODE
      The return code from the executed command indicating the success of the requested operation.
      static java.lang.String PARAM_STD_ERROR
      The standard error from the executed command.
      static java.lang.String PARAM_STD_OUTPUT
      The standard output from the executed command.
      static java.lang.String PARAM_STDIN_DEST
      The name of the entry attribute containing the path to where the standard input file can be copied on the remote machine.
      static java.lang.String PARAM_STDIN_SRC
      The name of the entry attribute containing the path to the standard input source file on the local machine.
      protected java.lang.String[] PARAM_STR_CONFIG_OPTIONS
      This array stores the names of the TDI GUI String parameters that can be configured (excluding those that may be set as attributes in the TDI input Entry).
      protected java.util.Properties props
      Stores the connection properties that have been configured
      protected TDIRXALogAdapter RXAlogger
      TDIRXALogAdapter to be used
      protected java.lang.String stdinDest
      The standard input details for the command that is to be executed.
      protected java.lang.String stdinSrc
      The standard input details for the command that is to be executed.

    • Constructor Summary

      Constructors 
      Constructor Description
      RemoteCmdLineFC()
      Remote Command Line FC constructor

    • Field Detail

      • PARAM_CONFIG_HOST

        public static final java.lang.String PARAM_CONFIG_HOST
        Hostname of Remote Machine (target)
        See Also:
        Constant Field Values

      • PARAM_CONFIG_USER

        public static final java.lang.String PARAM_CONFIG_USER
        The username to be used when connecting to target
        See Also:
        Constant Field Values

      • PARAM_CONFIG_PORT

        public static final java.lang.String PARAM_CONFIG_PORT
        The port to be used when establishing connection with target
        See Also:
        Constant Field Values

      • PARAM_CONFIG_PASSWD

        public static final java.lang.String PARAM_CONFIG_PASSWD
        User password to authenticate to the target
        See Also:
        Constant Field Values

      • PARAM_CONFIG_AS400CMDARGSENC

        public static final java.lang.String PARAM_CONFIG_AS400CMDARGSENC
        Character Encoding for AS400 Program cmdArgs
        See Also:
        Constant Field Values

      • PARAM_CONFIG_CONNTYPE

        public static final java.lang.String PARAM_CONFIG_CONNTYPE
        The connection type string.
        See Also:
        Constant Field Values

      • PARAM_CONFIG_COMMAND

        public static final java.lang.String PARAM_CONFIG_COMMAND
        Command to execute on target
        See Also:
        Constant Field Values

      • PARAM_CONFIG_TIMEOUT

        public static final java.lang.String PARAM_CONFIG_TIMEOUT
        Timeout duration for executing the command (ms)
        See Also:
        Constant Field Values

      • PARAM_CONFIG_KEYSTORE

        public static final java.lang.String PARAM_CONFIG_KEYSTORE
        Path to the local keystore to be used when connecting to the remote machine using the SSH protocol
        See Also:
        Constant Field Values

      • PARAM_CONFIG_PASSPHRASE

        public static final java.lang.String PARAM_CONFIG_PASSPHRASE
        The passphrase for the keystore
        See Also:
        Constant Field Values

      • PARAM_CONFIG_STDIN_SOURCE

        public static final java.lang.String PARAM_CONFIG_STDIN_SOURCE
        The local path to the standard input source file
        See Also:
        Constant Field Values

      • PARAM_CONFIG_STDIN_DESTN

        public static final java.lang.String PARAM_CONFIG_STDIN_DESTN
        The remote path to the standard input destination file
        See Also:
        Constant Field Values

      • PARAM_CONFIG_AS400_SSL

        public static final java.lang.String PARAM_CONFIG_AS400_SSL
        Enable or disable SSL over an AS400 connection
        See Also:
        Constant Field Values

      • PARAM_CONFIG_AS400_PROXY

        public static final java.lang.String PARAM_CONFIG_AS400_PROXY
        Proxy to be used if required for AS400 connection
        See Also:
        Constant Field Values

      • PARAM_CONFIG_AS400_RUNPROG

        public static final java.lang.String PARAM_CONFIG_AS400_RUNPROG
        Secondary mechanism for executing AS400 Programs
        See Also:
        Constant Field Values

      • PARAM_CONFIG_RXA_LOG

        public static final java.lang.String PARAM_CONFIG_RXA_LOG
        Enable or disable RXA internal logging
        See Also:
        Constant Field Values

      • PARAM_INPUT

        public static final java.lang.String PARAM_INPUT
        The name of the entry attribute containing the command to be executed on the target. This attribute should be contained in the TDI Entry object passed to the FC perform method.
        See Also:
        Constant Field Values

      • PARAM_ARGS

        public static final java.lang.String PARAM_ARGS
        The name of the entry attribute containing the command arguments. This multi-valued attribute contains String values, where each string value is a simple, or complex argument. Simple Argument example. ls -l /tmp (command.line="ls", command.args={"-l", "/tmp" } find . -name '*.log' -exec grep 'ERROR' {} \; -print (command.line="find", command.args={".", "-name", "'*.log'", "-exec", "grep", "'ERROR'", "{} \; -print" }
        See Also:
        Constant Field Values

      • PARAM_ARGS_DELIM

        public static final java.lang.String PARAM_ARGS_DELIM
        The name of the entry attribute specifing the command argument delimiter. If not specified the default is a single white space character.
        See Also:
        Constant Field Values

      • PARAM_RETURN_CODE

        public static final java.lang.String PARAM_RETURN_CODE
        The return code from the executed command indicating the success of the requested operation. This attribute is contained in the TDI Entry object returned by the FC perform method.
        See Also:
        Constant Field Values

      • PARAM_STD_OUTPUT

        public static final java.lang.String PARAM_STD_OUTPUT
        The standard output from the executed command. This attribute is contained in the TDI Entry object returned by the FC perform method.
        See Also:
        Constant Field Values

      • PARAM_STD_ERROR

        public static final java.lang.String PARAM_STD_ERROR
        The standard error from the executed command. This attribute is contained in the TDI Entry object returned by the FC perform method.
        See Also:
        Constant Field Values

      • PARAM_STDIN_SRC

        public static final java.lang.String PARAM_STDIN_SRC
        The name of the entry attribute containing the path to the standard input source file on the local machine. This attribute should be contained in the TDI Entry object passed to the FC perform method.
        See Also:
        Constant Field Values

      • PARAM_STDIN_DEST

        public static final java.lang.String PARAM_STDIN_DEST
        The name of the entry attribute containing the path to where the standard input file can be copied on the remote machine. This attribute should be contained in the TDI Entry object passed to the FC perform method.
        See Also:
        Constant Field Values

      • PARAM_HANDLE_TEXT_FILE

        public static final java.lang.String PARAM_HANDLE_TEXT_FILE
        Parameter to handle as text file
        See Also:
        Constant Field Values

      • PARAM_CONFIG_INITIAL_TIMEOUT

        public static final java.lang.String PARAM_CONFIG_INITIAL_TIMEOUT
        Timeout parameter of the connection
        See Also:
        Constant Field Values

      • PARAM_STR_CONFIG_OPTIONS

        protected final java.lang.String[] PARAM_STR_CONFIG_OPTIONS
        This array stores the names of the TDI GUI String parameters that can be configured (excluding those that may be set as attributes in the TDI input Entry).

      • PARAM_INT_CONFIG_OPTIONS

        protected final java.lang.String[] PARAM_INT_CONFIG_OPTIONS
        This array stores the names of the TDI GUI int parameters that can be configured.

      • PARAM_BOOL_CONFIG_OPTIONS

        protected final java.lang.String[] PARAM_BOOL_CONFIG_OPTIONS
        This array stores the names of the TDI GUI boolean parameters that can be configured (excluding those that may be set as attributes in the TDI input Entry).

      • executor

        protected CmdLineExecutor executor
        The executor object that connects to the appropriate machine to execute the command.

      • cmdToExecute

        protected java.lang.String cmdToExecute
        The command that is to be executed. Specified either through the TDI GUI or as an entry attribute called command.line

      • cmdArgs

        protected java.lang.String[] cmdArgs
        The command arguments to be appended.

      • cmdArgsDelim

        protected java.lang.String cmdArgsDelim
        The command arguments delimiter character. default is the space character.

      • stdinSrc

        protected java.lang.String stdinSrc
        The standard input details for the command that is to be executed. Specified either through the TDI GUI or as an entry attributes

      • stdinDest

        protected java.lang.String stdinDest
        The standard input details for the command that is to be executed. Specified either through the TDI GUI or as an entry attributes

      • initialized

        protected boolean initialized
        keep track of whether the fc has been initialized

      • props

        protected java.util.Properties props
        Stores the connection properties that have been configured

      • logproxy

        protected LogProxy logproxy
        The way to perform logging.

    • Constructor Detail

      • RemoteCmdLineFC

        public RemoteCmdLineFC()
        Remote Command Line FC constructor

    • Method Detail

      • perform

        public java.lang.Object perform​(java.lang.Object arg0)
                         throws ParamException,
                                GeneralCLFCException

        Execute the Command on the specified target. Initialize must be called prior to calling this method.

        The perform() method accepts an Entry object. If anything else is passed an Exception is thrown.

        The suppplied Entry object may contain zero or more of the following attributes:

        Configuration Item Available Attribute
        Command to Execute PARAM_INPUT
        Local Path to Stdin Source File PARAM_STDIN_SRC
        Remote Path to Stdin Destination File PARAM_STDIN_DEST

        NOTE: Values for the command and standard input parameters may also be configured on the TDI GUI. In the event of one or more of these parameter values being specified both on the TDI GUI and as attributes in the Entry object, the value provided within the TDI Entry object will have precedence over the value supplied on the GUI. For instance, if a value is provided for the command both on the GUI and as an attribute called PARAM_INPUT in the Entry object then the value configured on the GUI will be disregarded.

        On response the Entry will contain the attributes command.out and command.error and command.returnCode. Attributes command.out and command.error will have java.lang.String values representing the standard output and standard error returned from executing the command respectively. The attribute command.returnCode will have a java.lang.Integer value containing the return code that resulted from executing the command. These attributes can be used to determine the success/failure of the operation.

        Parameters:
        arg0 - must be Entry
        Returns:
        Entry
        Throws:
        GeneralCLFCException - when errors occur executing the command
        ParamException - when insufficient/incorrect parameters provided

      • getVersion

        public java.lang.String getVersion()
        Gets the version of this FC.
        Returns:
        String version + build date

      • terminate

        public void terminate()
               throws GeneralCLFCException,
                      java.lang.Exception
        This function is called when the connector is no longer needed by the user in the Assembly Line or script. Always calls the superclass terminate method which will take care of releasing resources, closing parsers etc.
        Specified by:
        terminate in interface FunctionInterface
        Overrides:
        terminate in class Function
        Throws:
        java.lang.Exception
        GeneralCLFCException

      • initialize

        public void initialize​(java.lang.Object o)
                throws GeneralCLFCException,
                       java.lang.Exception
        This function is called once after the connector configuration file has been provided by the caller.
        Specified by:
        initialize in interface FunctionInterface
        Overrides:
        initialize in class Function
        Parameters:
        o - The configuration object from TDI.
        Throws:
        java.lang.Exception - If super class initialize fails.
        GeneralCLFCException - If the connection cannot be prepared i.e. not all attributes have been provided.

      • getRXACompatableLogger

        protected com.ibm.tivoli.remoteaccess.log.Logger getRXACompatableLogger()
        Gets an RXA compatible logger
        Returns:
        the logger

      • logError

        public void logError​(java.lang.String err)
        Log the specified error message.
        Parameters:
        err - Error to be logged

      • logmsg

        public void logmsg​(java.lang.String msg)
        Log the specified debug message.
        Specified by:
        logmsg in interface FunctionInterface
        Overrides:
        logmsg in class Function
        Parameters:
        msg - Message to be logged

      • logInfo

        public void logInfo​(java.lang.String msg)
        Log the specified info message
        Parameters:
        msg - Message to be logged

      • setLog

        public void setLog​(Log lg)
        Set the log for the Function Component to the specified Log
        Specified by:
        setLog in interface FunctionInterface
        Overrides:
        setLog in class Function
        Parameters:
        lg - The desired log

      • getExecutor

        public CmdLineExecutor getExecutor()
        This function is called to return the CmdLineExecutor that has been initialized by the FC. In the event that a remote connection has been established, the RemoteCmdLineExecutor.getRXAProtocol() method can be used to return a RXA connection protocol object that can be used to perform operations permitted by the RXA toolkit.
        Returns:
        CmdLineExecutor object that has been initialised to perform the command.