NAME

FleetConf::Agent::Parser::Stmt::COMMAND - COMMAND command

SYNOPSIS

  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

DESCRIPTION

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.

EXPLANATION

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 or EXEC_IF_OPTION command is executed. The command-line can be further modified through the use of OPTION or OPTION_IF commands.

The 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".

The 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

The 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 or 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

COMMAND-LINE EXECUTION

Once the command-line has been constructed via the COMMAND and OPTION or OPTION_IF commands and then execution has been requested through EXEC or EXEC_IF_OPTION, the following processing is done:

1. The first non-whitespace string or first quoted-string found in the command-line is checked to see if it is a relative path or not. (This determination is performed using the 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.

2. The command-line is executed and all output from the command is captured and logged.

   If IGNORE_FAILURE is specified (either in EXEC_COMMAND, EXEC, or 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.

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@users.sourceforge.net>

COPYRIGHT AND LICENSE

Copyright 2005 Andrew Sterling Hanenkamp. All Rights Reserved.

FleetConf is distributed and licensed under the same terms as Perl itself.