As an alternative to running server instances from the Administration Perspective, an agent command line utility is provided. The utility can be used directly from the command line, or incorporated into scripts. The agent command line utility is installed into the bin directory of the Orchestrator Server. A clagent.txt file is included in the help directory installed to the Orchestrator server location.
The commands allowing you to interface with an agent server from the command line are divided into the following three tables:
For information about running the agent server instances from the Administration Perspective, see Command and Control.
Before using the command line agent utility to create instances and deploy packages, export xml files for the following and know the names and locations of the files. If you are using the command line agent utility to run server instances and manage business processes, these prerequisites are not required.
Endpoint definitions; see Exporting from the Directory.
Runtime instance configuration; see Exporting Runtime Instance Configuration.
Package Bindings; see Exporting Package Bindings.
|
Command |
|
|
|
clagent |
Description |
Starts the command line tool for the Orchestrator Agent. clagent connects to an existing instance using the host and port information. |
|
|
Parameters -h/--host -p/--port --help -I/--interactive
-U/--user -P/--password |
The host of the Agent; default is localhost The port on which the Agent is listening; default value is 7000 List available commands The clagent --interactive switch places the clagent into interactive mode after executing the specified command. You can enter subsequent commands interactively; you enter the command and view the results. Note: The command "clagent --interactive" is synonymous with the command "clagent". Username Password |
If the host and port parameters are not specified at startup, clagent uses the default host, localhost, and default port, 7000.
Parameters can be used in either of the following ways:
1. Using the full parameter name. The parameter name is immediately preceded by two dashes:
--<parameter>
For example:
clagent --host localhost --port 7000 --interactive --user rsmith --password xxrawer
2. Using the aliased parameter name. Each parameter is aliased to use a - and the first letter of the parameter name. The alias for --host is -h.
-<parameter alias (single alpha character)>
For example:
clagent -h localhost -p 7000 -I -U rsmith -P xxrawer
When interactive mode is specified for running clagent, additional commands can be entered without the clagent, host, and port for the command.
For example:
1. Start the clagent in interactive mode:
clagent -h mainhost -p 3583 -I list_instances -U rsmith -P xxrawer
To retrieve the engine state for the prime instance enter:
get_engine_state -i prime
The clagent -h mainhost -p 3583 is not required on subsequent commands entered.
2. Start the clagent without interactive mode:
clagent -h mainhost -p 3583 list_instances -U rsmith -P xxrawer
To retrieve the engine state for the prime instance enter:
clagent -h mainhost -p 3583 get_engine_state -i prime -U rsmith -P xxrawer
The clagent -h mainhost -p 3583 is required on subsequent commands entered.
Multiple commands can be strung together to be performed in the specified order.
The following example:
Connects to the mainhost host on port number 7000.
Returns the engine state for the prime instance, exiting if the engine is not in a running state.
Pauses the engine for the prime instance.
clagent -h mainhost -p 7000 get_engine_state -b -i prime pause_engine -i prime -U rsmith -P xxrawer
This example starts several instances:
clagent -h mainhost -p 7000 start_engine -i prime1 -i prime2 -i prime3 -U rsmith -P xxrawer
The username and password are required by the agent to access the directory services repository. The clagent program itself (and not just its various command processors) requires these parameters. Both interactive and non-interactive invocations of the program require a single specification of these two parameters.
Interactive:
$ clagent -U jdoe -P secret
clagent> list_instances
...
clagent> start_engine --instance prime
...
clagent> stop_engine --instance prime
...
clagent> exit
Non-interactive equivalent:
$ clagent -U jdoe -P secret list_instances
$ clagent -U jdoe -P secret start_engine --instance prime
$ clagent -U jdoe -P secret stop_engine --instance prime
|
Command |
|
|
|
|
|
|
|
create_instance |
Description |
Creates a new runtime instance |
|
|
Parameters |
|
|
|
-i / --instance |
A name for the new instance required |
|
|
Usage |
clagent create_instance -i <instance name> |
|
|
|
|
|
deploy_instance |
Description |
Deploy a package at a runtime instance |
|
|
Parameters |
|
|
|
-E / --endpoint |
Optional; the name of the endpoint data file; default value is "(unspecified)" |
|
|
-i / --instance |
The name of the instance |
|
|
-P/ --package |
The name of the package that will be deployed |
|
|
-B/ --binding |
The name of a binding document |
|
|
-C/ --config |
The name of a configuration file |
|
|
Usage |
clagent deploy_instance [-E <endpoint file>] -i <instance name> -P <package name> -B <binding doc> -C <config file> |
|
|
|
|
|
reconfigure_instance |
Description |
Reconfigure an already deployed runtime instance |
|
|
Parameters |
|
|
|
-i / --instance |
The name of the instance |
|
|
-C/ --config |
The name of the configuration file |
|
|
Usage |
clagent reconfigure_instance -i <instance name> -C <config file> |
|
Command |
|
|
|
abort_engine |
Description |
Abort the engine for the specified instance. This command is typically used for engines in an invalid state; the command aborts the engine and cleans the runtime files (removes the .pid file). The preferred stop_engine command may not work to stop an engine in an invalid state. |
|
|
Parameters |
|
|
|
-i / --instance |
The name of the runtime instance |
|
|
Usage |
clagent abort_engine -i<instance name> |
|
|
|
|
|
delete_instance |
Description |
Delete the engine for the specified instance |
|
|
Parameters |
|
|
|
-i / --instance |
The name of the runtime instance |
|
|
Usage |
clagent delete_instance -i<instance name> |
|
|
|
|
|
exit |
Description |
Exit interactive mode (interactive mode only) |
|
|
Parameters |
|
|
|
Usage |
clagent exit |
|
|
|
|
|
get_autostart |
Description |
Get the autostart mode for the specified instance |
|
|
Parameters |
|
|
|
-i / --instance |
The name of the runtime instance |
|
|
Usage |
get_autostart -i<instance name> |
|
|
|
|
|
get_engine_state |
Description |
Determine the current state of the engine for the specified instance. An engine can be in the following states: running, stopped, suspended, and invalid. |
|
|
Parameters |
|
|
|
-i / --instance |
The name of the runtime instance |
|
|
-b / --break |
Exit if the engine is not in a running state |
|
|
Usage |
get_instance_state -b -i<instance name> |
|
|
|
|
|
help |
Description |
List the available commands and command usages (interactive mode only) |
|
|
Parameters |
|
|
|
none |
|
|
|
Usage |
For interactive mode: clagent help <command name> or clagent help For non-interactive mode: clagent --help or clagent -? |
|
|
|
|
|
list_instances |
Description |
List the available instance on the Agent |
|
|
Parameters |
|
|
|
none |
|
|
|
Usage |
clagent list_instances |
|
|
|
|
|
pause_engine |
Description |
Pause the engine for the specified instance |
|
|
Parameters |
|
|
|
-i / --instance |
The name of the runtime instance |
|
|
Usage |
clagent pause_engine -i<instance name> |
|
|
|
|
|
ping_engine |
Description |
Ping the engine for the specified instance |
|
|
Parameters |
|
|
|
-i / --instance |
The name of the runtime instance |
|
|
-b / --break |
Exit if the engine's ping is not successful |
|
|
Usage |
clagent _ping_engine -i<instance name> |
|
|
|
|
|
purge_runtime_data |
Description |
Purges the engine's runtime state on a non-running engine |
|
|
Parameters |
|
|
|
-i / --instance |
The name of the runtime instance |
|
|
Usage |
clagent purge_runtime_data -i<instance name> |
|
|
|
|
|
resume_engine |
Description |
Resume a suspended engine for the specified instance |
|
|
Parameters |
|
|
|
-i / --instance |
The name of the runtime instance |
|
|
Usage |
clagent resume_engine -i<instance name> |
|
|
|
|
|
set_autostart |
Description |
Set the autostart mode for the specified instance |
|
|
Parameters |
|
|
|
-m/--mode |
Autostart mode. Can be set to TRUE or FALSE. If set to TRUE, the instance starts automatically when the agent is started. |
|
|
-i/--instance |
The name of the runtime instance |
|
|
Usage |
clagent set_autostart -m<mode> -i<instance name> |
|
|
|
|
|
start_engine |
Description |
Start the engine for the specified instance |
|
|
Parameters |
|
|
|
-i / --instance |
The name of the runtime instance |
|
|
Usage |
clagent start_engine -i<instance name> |
|
|
|
|
|
stop_engine |
Description |
Stop the engine for the specific instance |
|
|
Parameters |
|
|
|
-i / --instance |
The name of the runtime instance |
|
|
Usage |
clagent stop_engine -i<instance name> |
|
Command |
|
|
|
get_log_file |
Description |
Retrieve the specified log file from the specified instance |
|
|
Parameters |
|
|
|
-o/--output |
The name of the output file |
|
|
-i / --instance |
The name of the runtime instance |
|
|
-f/--file |
The name of the log file to retrieve |
|
|
Usage |
clagent get_log_file -o<outfile name> -i<instance name> -f<log file name> |
|
|
|
|
|
get_log_file_lines |
Description |
|
|
|
Parameters |
|
|
|
-l/--lines |
The number of log file lines to retrieve; default is 500 |
|
|
-i / --instance |
The name of the runtime instance |
|
|
-f/--file |
The name of the log file whose contents to retrieve |
|
|
Usage |
clagent get_log_file_lines -l<number of lines> -i<instance name> -f<log file name> |
|
|
|
|
|
get_log_file_names |
Description |
Retrieve a list of log file names from the specified instance |
|
|
Parameters |
|
|
|
-i / --instance |
The name of the runtime instance |
|
|
Usage |
clagent get_log_file_names -i<instance name> |
|
|
|
|
|
query_all_failed_processes |
Description |
Query engine for list of all failed business processes for the specified instance |
|
|
Parameters |
|
|
|
-i/--instance |
The name of the runtime instance |
|
|
Usage |
clagent query_all_failed_processes -i<instance name> |
|
|
|
|
|
query_failed_processes_of_type |
Description |
Query engine for a list of failed business processes of the specified type for the specified instance |
|
|
Parameters |
|
|
|
-i/--instance |
The name of the runtime instance |
|
|
-t/--type |
The business process type identifier |
|
|
Usage |
clagent query_failed_processes_of_type -i<instance name> -t<type> |
|
|
|
|
|
query_process_stats |
Description |
Query the engine for business process statistics |
|
|
Parameters |
|
|
|
-i/--instance |
The name of the runtime instance |
|
|
Usage |
clagent query_process_stats -i<instance name> |
|
|
|
|
|
query_process_stats_of_type |
Description |
Query the engine for business process statistics for the specified type |
|
|
Parameters |
|
|
|
-i/--instance |
The name of the runtime instance |
|
|
-t/--type |
The business process type identifier |
|
|
Usage |
clagent query_process_stats_of_type -i<instance name> -t<type> |
|
|
|
|
|
query_process_types |
Description |
Query the engine for a list of all business process types |
|
|
Parameters |
|
|
|
-i/--instance |
The name of the runtime instance |
|
|
Usage |
clagent query_process_types -i<instance name> |
|
|
|
|
|
recover_all_processes |
Description |
Recover all failed business processes |
|
|
Parameters |
|
|
|
-i/--instance |
The name of the runtime instance |
|
|
Usage |
clagent recover_all_processes -i<instance name> |
|
|
|
|
|
recover_processes |
Description |
Recover specified failed business processes |
|
|
Parameters |
|
|
|
-i/--instance |
The name of the runtime instance |
|
|
-d/--pid |
One or more comma-delimited business process identifiers |
|
|
Usage |
clagent recover_processes -i<instance name> -d<pid list> |
|
|
|
|
|
recover_processes_of_type |
Description |
Recover failed business processes of a specified type |
|
|
Parameters |
|
|
|
-i/--instance |
The name of the runtime instance |
|
|
-t/--type |
The business process type identifier |
|
|
Usage |
clagent recover_processes_of_type -i<instance name> -t<type> |
|
|
|
|
|
remove_all_failed_processes |
Description |
Remove all failed business processes |
|
|
Parameters |
|
|
|
-i/--instance |
The name of the runtime instance |
|
|
-f--file |
The name of the log file to retrieve |
|
|
Usage |
clagent remove_all_failed_processes -i<instance name> |
|
|
|
|
|
remove_failed_processes |
Description |
Remove specified failed business processes |
|
|
Parameters |
|
|
|
-i/--instance |
The name of the runtime instance |
|
|
-d/--pid |
One or more comma-delimited business process identifiers |
|
|
Usage |
clagent remove_failed_processes -i<instance name> -d<pid list> |
|
|
|
|
|
remove_failed_processes_of_type |
Description |
Remove failed business processes of the specified type |
|
|
Parameters |
|
|
|
-i/--instance |
The name of the runtime instance |
|
|
-t/--type |
The business process type identifier |
|
|
Usage |
clagent remove_failed_processes_of_type -i<instance name> -t<type> |
|
Error |
Description |
|
Usage Error With Command |
A usage error related to a command. |
|
Usage Error With Parameter |
A usage error related to a parameter. |
|
Command Error |
A command error. |
|
Unknown Error |
Identifies an unknown type of error. |
|
Integer Parameter Parsing Error |
Failed to initialize the identified integer parameter. Error parsing the identified default value string. Failed to parse the identified integer parameter. Error parsing the identified value string. |