expected-values

Edit online

Specifies the expected values for which to wait before a command completes. Use in conjunction with the check-every and wait options.

When you use the {--expected | -e}, {--check-every | -c}, and {--wait | -w} options, each {--check-every | -c} seconds the command is executed and the results are examined for the values specified with the {--expected | -e} option. The command is successful if the command returns the expected values within the wait time. The command fails if the command does not return the expected values within the wait time.

Syntax

{--expected-values | -e} values

Arguments

Argument Description
values Specifies the values that must be present in the output for a command to complete. Use a comma to separate each value. Always place quotes around the value, for example: 
--expected-values "STOPPED,ONLINE"

The values can include the wildcard character (*) that represents any number of characters. For example, RUNN*,*NLINE,OFF*NE.

Operators

The command supports the following operators listed in the table by operator precedence:

Operator Description
! Negates the argument to the right, for example !RUNNING returns all responses that do not contain the text “RUNNING”.
, Specifies the sequence in which the values will get executed. For example, if you specify STOPPED,UNKNOWN,ONLINE, the command first checks for the STOPPED run-time status. After STOPPED, the command checks for the UNKNOWN status, and after that it checks for ONLINE. If any of the run-time statuses do not occur before the command times out, the command returns an error indicating the missing statuses.

When you specify multiple values, the command checks for all values and completes successfully only if all of them are present.

& Indicates that the value includes a logical AND operator. For example, RUNNING&RESPONSIVE checks if the output contains both RUNNING and RESPONSIVE.
| Indicates that the value includes a logical OR operator, for example the following command checks if the output contains either DONE or WARNING: 
--expected "DONE|WARNING"

Usage Notes

  • You can define the expected values as a complex expression that contains more than one operator. The order of the operations is controlled by using brackets, for example:"!RU*NG|OFFLINE&!ONLINE" and "(!RU*NG)|(OFFLINE&(!ONLINE))" follow the same order of operations, but "(!(RU*NG|OFFLINE))&(!ONLINE)" follows a different operator precedence.
  • If a command is executed from a shell on Windows or UNIX operating systems, the exclamation mark is considered a special character. Use the following escape characters to escape (!):
    • (^) on Windows, for example "^!RUNNING"
    • (\) on UNIX/Linux, for example "\!RUNNING"
  • The use of the {--expected-values | -e}, {--wait | -w}, and {--check-every | -c} options is helpful with commands that perform actions that might take several seconds or minutes to complete. Depending on your use case, these options might be helpful with any command. However, they are most helpful with the lifecycle and monitoring commands because they allow you to reliably execute the commands.
  • If you specify the {--expected-values | -e} option, but omit the {--check-every | -c} option, the command uses the value from the CC_CHECK_EVERY environment variable. If the CC_CHECK_EVERY environment variable is not set, the command uses 15 seconds.
  • If you specify the {--expected-values | -e} option, but omit the {--wait | -w} option, the command uses the value from the CC_WAIT environment variable. If the CC_WAIT environment variable is not set, the command uses 15 seconds.

Example

To wait 180 seconds for a command to return the value “STOPPED”, then “ONLINE”, checking every 30 seconds for the expected results: 

--expected-values "STOPPED,ONLINE" --wait 180 --check-every 30