Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.ibm.di.fc.remotecmdlnfc
Class RemoteCmdLineFC

java.lang.Object
  extended by com.ibm.di.fc.Function
      extended by com.ibm.di.fc.remotecmdlnfc.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:

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:

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
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.
protected  boolean terminated
          keep track of whether the fc has been terminated
 
Fields inherited from class com.ibm.di.fc.Function
logger
 
Constructor Summary
RemoteCmdLineFC()
          Remote Command Line FC constructor
 
Method Summary
 CmdLineExecutor getExecutor()
          This function is called to return the CmdLineExecutor that has been initialized by the FC.
protected  com.ibm.tivoli.remoteaccess.log.Logger getRXACompatableLogger()
          Gets an RXA compatible logger
 java.lang.String getVersion()
          Gets the version of this FC.
 void initialize(java.lang.Object o)
          This function is called once after the connector configuration file has been provided by the caller.
 void logError(java.lang.String err)
          Log the specified error message.
 void logInfo(java.lang.String msg)
          Log the specified info message
 void logmsg(java.lang.String msg)
          Log the specified debug message.
 java.lang.Object perform(java.lang.Object arg0)
           Execute the Command on the specified target.
 void setLog(Log lg)
          Set the log for the Function Component to the specified Log
 void terminate()
          This function is called when the connector is no longer needed by the user in the Assembly Line or script.
 
Methods inherited from class com.ibm.di.fc.Function
debug, getConfiguration, getContext, getDebug, getLog, getParam, getRSInterface, getUI, initialize, querySchema, setConfiguration, setContext, setDebug, setParam, setRSInterface, updateSchema, verifyInitialized
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

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

terminated

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

props

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

logproxy

protected LogProxy logproxy
The way to perform logging.

RXAlogger

protected TDIRXALogAdapter RXAlogger
TDIRXALogAdapter to be used

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.
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD