How to write a CLI macro file

The following explains how to write a CLI macro file.

CLI lines

CLI lines without CLIPARMS
```
△₀CLI-name[△₁CLI-parameter]
```
You can run the BCM Web API request by specifying the CLI name for the cliname key and specifying the CLI parameter for the operands key.

The CLI name (the cliname key) and CLI parameter (the operands key) must be written according to the request format of the BCM Web API request that runs the CLI command.

The portion from the second word to the end of the line is treated as the CLI parameter. CLI parameters are optional.

Specify a CLI name by using no more than eight alphanumeric characters. If the CLI parameter contains a control code, the macro execution will end with an error.

If the CLI parameter contains double quotation marks, a forward slash, or a backslash, specify them as is.
CLI lines with CLIPARMS
```
△₀CLI-name[△₁CLI-parameter]△₁[△₀
CLIPARMS-record
CLIPARMS-record
...
]
```
In the [△₁CLI-parameter] portion, square brackets [ ] indicate that this portion is optional. However, the subsequent square brackets [ ] indicate array notation in JSON format.

You can run the BCM Web API request by specifying the CLI name for the cliname key, specifying the CLI parameter for the operands key, and specifying the CLIPARMS record between the quotation marks in the array of the CLIPARMS key.

The CLI name, CLI parameter, and CLIPARMS record must be written according to the request format of the BCM Web API request that runs the CLI command.

Specify a CLI name by using no more than eight alphanumeric characters.

If the CLIPARMS record contains a control code, the macro execution will end with an error.

If the CLI parameter contains double quotation marks, a forward slash, or a backslash, specify them as is.

If a line ends (excluding spaces and tabs) with a left square bracket ([), the lines preceding the line immediately before the line starting with a right square bracket (]) are considered the CLIPARMS record (not the CLI name).

Use no more than 80 characters in each line of the CLIPARMS record.

If the first character of the CLIPARMS record is a right square bracket (]), it is assumed that the CLI record ends. Even if the second and subsequent characters are specified, they are ignored and no error will occur.

Reaching the EOF before a right square bracket (]) does not result in an error. (Lines up to the last line of the file are considered the CLIPARMS record.)
The maximum number of CLIPARMS records in each CLI command line with CLIPARMS is 1000.

The maximum combined number of CLI command lines with CLIPARMS and CLI command lines without CLIPARMS in a file is 30 lines.

Label lines

△₀label-name:

Specify the label name for the branching destination of the GOTO, SUCCESS, WARN, and ERROR lines.

Specify a label name by using no more than 255 characters. The characters are case-insensitive.

If the first word ends followed by a colon (:), the word is considered a label name. The second and subsequent words are ignored.

Branching lines

Unconditional branching line
```
△₀GOTO△₁label-name
```
Resumes execution from the line following label-name: (label line). The status (return code) of the most recently executed CLI command is not taken into account. Whether the CLI command was running immediately beforehand is also ignored.
Branching line for a normal termination
```
△₀SUCCESS△₁label-name
```
Resumes execution from the line following label-name: (label line) if the return code of the CLI command executed immediately beforehand is 0.
Branching line for a warning termination
```
△₀WARN△₁label-name
```
Resumes execution from the line following label-name: (label line) if the return code of the CLI command executed immediately beforehand is one of the following:
- YKLOAD: 1 to 8 (inclusive)
- YKQUERY: 1 to 8 (inclusive), or 24
- YKRMTCDV: 1 to 12 (inclusive)
- Others: 1 to 4 (inclusive)
Branching line for an abnormal termination
```
△₀ERROR△₁label-name
```
If the return code of the most recently executed CLI command is in the following range, or if no BCM Web API response is obtained, execution resumes from the line following label-name: (label line):
- YKQUERY, YKLOAD: Less than 0, or greater than or equal to 9
- YKRMTCDV: Less than 0, or greater than or equal to 13
- Others: Less than 0, or greater than or equal to 5

Common rules for branching lines

If there is no label name, execution ends with an error.
If the label line that defines the label specified for label-name in the branching line does not exist, execution ends with an error.
The first word (keyword) is case-insensitive.
The second word (the word following the keyword) is treated as the label name. The words after the second word are ignored.

Annotation lines

# annotation-string

If you add a hash symbol (#) to the first character, the line is treated as an annotation line, and is ignored when the command is executed.

Blank lines

Blank lines or lines with tabs only.

For CLI lines with CLIPARMS, blank lines are ignored. For CLI lines with CLIPARMS, blank lines are treated as a single-character blank CLIPARMS record.

CLI macro execution order

The BCM Web API runs the CLI commands in the CLI command lines in order, starting from the top of the CLI macro file.

If there is a branching line between CLI command lines, and the conditions of that branching line are met, macro execution resumes from the line following the label line indicated by the label name. Branching lines other than unconditional branching lines are ignored even if they exist before the CLI command line at the branching destination.

If the CLI execution result satisfies the conditions of an abnormal termination branching line, and there are no abnormal termination branching lines between CLI command lines, the macro execution will end.