FleetConf::Agent::Parser::Stmt::COMMAND - COMMAND command
NAME Some-Agent MNEMONIC foo WORKFLOW Null COMMAND run-something -option1 OPTION -option2 EXEC EXEC_COMMAND IGNORE_FAILURE cmd.exe /? COMMAND foobar OPTION_IF (FALSE) --some-option EXEC_IF_OPTION
THis commands adds the ability to execute external system commands.
The BNF for the
COMMAND commands is:
agent_command +::= command_command | option_command | exec_command command_command ::= "COMMAND" bare_string EOL | "EXEC_COMMAND" ("IGNORE_FAILURE")(?) bare_string EOL option_command ::= "OPTION" bare_string EOL | "OPTION_IF" "(" boolean_expression ")" bare_string EOL exec_command ::= "EXEC" ("IGNORE_FAILURE")(?) EOL | "EXEC_IF_OPTION" ("IGNORE_FAILURE")(?) EOL
These statements are evaluted only during the run phase.
The proper use of these commands may not be immediately obvious, but they can be used in interesting combinations to produce flexible results.
The simplest command is
EXEC_COMMAND. This command always stands on it's own. It immediately executes the given command-line (see "COMMAND-LINE EXECUTION" below).
Otherwise, all commands start with the
COMMAND command. This should be followed by the name of the command to execute. The command is not executed unless (and until) a
EXEC_IF_OPTION command is executed. The command-line can be further modified through the use of
OPTION command appends any text following it to the command-line specified by the most recent
COMMAND command. Each option appends to the end. Thus,
COMMAND a OPTION b OPTION c OPTION d EXEC
would attempt to execute the command-line "
a b c d".
OPTION_IF command is a short-cut for appending items that should only be conditionally added. That is:
OPTION_IF (expr) string
is short-hand for:
WHEN expr DO OPTION string END
EXEC command causes the command to be immediately executed according to the plan outlined in "COMMAND-LINE EXECUTION". The
EXEC_IF_OPTION command also causes the command to be executed immediately, but only if one or more
OPTION_IF commands was processed since the last
COMMAND command. Thus, the following would never execute:
COMMAND foo WHEN FALSE DO OPTION bar END OPTION_IF (FALSE) baz EXEC_IF_OPTION
Once the command-line has been constructed via the
OPTION_IF commands and then execution has been requested through
EXEC_IF_OPTION, the following processing is done:
file_name_is_absolute()method of File::Spec as determining this is non-trivial and platform dependent.)
If the path is relative, then the "
safe_path" option in the FleetConf configuration is checked to see if an executable can be found in the relative path. If not, then an error occurs and no further processing is performed. If so, the full path to that command is quoted and used to replace the original command name.
If the path is absolute, then the path is quoted and put back into the original command-line.
IGNORE_FAILURE is specified (either in
EXEC_IF_OPTION), then the return value of the program is ignored and success is recorded.
Otherwise, a non-zero return from the command-line indicates a failure and the return value is logged as an error and an error is returned by the command.
Andrew Sterling Hanenkamp, <firstname.lastname@example.org>
Copyright 2005 Andrew Sterling Hanenkamp. All Rights Reserved.
FleetConf is distributed and licensed under the same terms as Perl itself.