14.4.5 How to specify a condition match

If you specify conditions in the --match option, you can return as the return code a value that indicates whether the execution results satisfy the condition. If the specified condition is satisfied, 0 is returned; if not, 1 is returned. For details, see the description of each subcommand's return codes. The information displayed as the results of subcommand processing is the same as when this option is omitted.

If the --match option is specified together with the --filter option, a value is returned as the return code that indicates whether the results obtained after filtering satisfy the condition. If the results are not displayed due to a warning, for example, 1 is returned.

When conditions are evaluated, values that are not displayed in cells are treated as if they were displayed. Cells with no data are treated as null character strings.

If the specified conditions are invalid, the command's execution fails.

Organization of this subsection

(1) Option specification format (BNF notation)
(2) Arguments
(3) Execution example

(1) Option specification format (BNF notation)

--match matching-condition
matching-condition ::= Boolean-function-condition|Value-function-condition|summary-condition
 
Boolean-function-condition ::= Boolean-function-name"("row-condition")"
                      Boolean-function-name ::= ALL|EXIST
Value-function-condition ::= Value-function-name"("row-condition")"comparison-operator-(character-string) character-string
                   |Value-function-name"("row-condition")"comparison-operator-(numeric-value) numeric-value
                    Value-function-name ::= COUNT
summary-condition ::= summary-name comparison-operator-(character-string) character-string
                   |summary-name comparison-operator-(numeric-value) numeric-value
 
row-condition ::= column-condition|column-condition logical-operator column-condition
column-condition ::= column-name comparison-operator-(character-string) character-string
               |column-name comparison-operator-(numeric-value) numeric-value
 
comparison-operator-(character-string) ::= "=="|"!="
comparison-operator-(numeric-value) ::= ">"|"<"|">="|"<="
logical-operator ::= "&&"|"||"
 
character-string ::= String-character-string
numeric-value ::= numeric-value-that-can-be-converted-by-Long.parseLong()

Important note

Enclose the entire condition in double quotation marks (") in the following cases:

summary-name, column-name, or character-string contains a space.
comparison-operator-(numeric-value) is specified.

If such a condition is not enclosed in double quotation marks ("), it might be treated as separate arguments or redirected incorrectly.

Reference note: For details about how to interpret the BNF notation, see 14.4.4(1) Option specification format (BNF notation).

To Page Top

(2) Arguments

(a) matching-condition

This argument specifies Boolean-function-condition, Value-function-condition, or summary-condition.

(b) Boolean-function-condition

This argument specifies Boolean-function-name"("row-condition")".

(c) Boolean-function-name

You can specify the functions shown in the following table.

Table 14‒60: Boolean functions that can be specified in the --match option
No.	Function	Description
1	`ALL`(`row-condition`)	Whether all rows satisfy the row condition
2	`EXIST`(`row-condition`)	Whether at least one row satisfies the row condition

(d) Value-function-condition

This argument specifies Value-function-name"("row-condition")"comparison-operator-(character-string) character-string or Value-function-name"("row-condition")"comparison-operator-(numeric-value) numeric-value.

(e) Value-function-name

You can specify the Value function shown in the following table.

Table 14‒61: Value function that can be specified in the --match option
No.	Function	Description
1	`COUNT`(`row-condition`)	Returns the number of rows that satisfy the row condition

(f) summary-condition

This argument specifies summary-name comparison-operator-(character-string) character-string or summary-name comparison-operator-(numeric-value) numeric-value.

(g) summary-name

This argument specifies a summary name for the information that is displayed.

A summary name can be specified regardless of whether the --format and --column options are specified.

Summary names cannot be specified if their display depends on whether an option other than --format or --column is specified. For example, the summary names that are displayed only when the -v option is specified cannot be specified if the -v option is not specified.

(h) row-condition

This argument specifies column-condition or column-condition logical-operator column-condition.

(i) column-condition

This argument specifies column-name comparison-operator-(character-string) character-string or column-name comparison-operator-(numeric-value) numeric-value.

(j) column-name

This argument specifies column names for the content to be displayed.

A column name can be specified regardless of whether the --format and --column options are specified. However, column names cannot be specified if their display depends on whether an option other than --format or --column is specified. For example, the column names that are displayed only when the -v option is specified cannot be specified if the -v option is not specified.

(k) comparison-operator-(character-string)

You can specify the comparison operators shown in the following table.

Table 14‒62: Comparison operators that can be specified in the --match option (character string)
No.	Comparison operator	Example	Description
1	`==`	`A` `==` `B`	Whether the pattern of character string `A` matches the pattern of character string `B` (case-sensitive)
2	`!=`	`A` `!=` `B`	Whether the pattern of character string `A` does not match the pattern of character string `B` (case-sensitive)

(l) comparison-operator-(numeric-value)

You can specify the comparison operators shown in the following table.

Table 14‒63: Comparison operators that can be specified in the --match option (numeric value)
No.	Comparison operator	Example	Description
1	`>`	`A` `>` `B`	Whether `A` as converted to a `long` value is greater than `B` as converted to a `long` value (if there is no data for `A`, the condition is false)
2	`<`	`A` `<` `B`	Whether `A` as converted to a `long` value is less than `B` that as converted to a `long` value (if there is no data for `A`, the condition is false)
3	`>=`	`A` `>=` `B`	Whether `A` as converted to a `long` value is equal to or greater than `B` as converted to a `long` value (if there is no data for `A`, the condition is false)
4	`<=`	`A` `<=` `B`	Whether `A` as converted to a `long` value is equal to or less than `B` as converted to a `long` value (if there is no data for `A`, the condition is false)

(m) logical-operator

You can specify the logical operators shown in the table below.

If multiple logical operators are specified, they are evaluated sequentially from left to right.

Table 14‒64: Logical operators that can be specified in the --match option
No.	Logical operator	Example	Description
1	`&&`	`A` `&&` `B`	`A` and `B` (if `A` and `B` are both true, the condition is true; otherwise, the condition is false)
2	`\|\|`	`A` `\|\|` `B`	`A` or `B` (if `A` and `B` are both false, the condition is false; otherwise, the condition is true)