### 2.3.75. INCLUDE

Executes RealView Debugger CLI commands stored in the specified script file.

#### Syntax

`INCLUDE` [/D] [/S] `filename`

where:

`/D`

Steps through the CLI commands in the script file. Before each command is executed, it is displayed in the Output view, together with the following prompt:

`Press ENTER to execute the line...`

If a DEFINE command is encountered, then the macro definition is executed completely. That is, the macro code is not stepped.

### Note

Commands from included script files are stepped only if you add the `/D` qualifier to each `INCLUDE` command used in your main script.

`/S`

Stops the commands in the INCLUDE file being echoed to the display. However, the commands are still added to the command history list.

### Note

If your main script file includes additional script files using the `/D` qualifier, then the commands in the additional script files are still stepped.

`filename`

Specifies the command file to be read. Quotation marks are optional, but see Rules for specifying filenames in the INCLUDE command for details on how to specify filenames that include a path.

### Note

If you specify both the `/D` and `/S` qualifiers, then the behavior depends on the order that you specify them.

#### Description

The INCLUDE command executes a group of commands stored in the specified file as though they were entered from the keyboard. By default, commands in the file are executed until the end of the file is reached or an error occurs. However, you can step through the commands if you want to debug the INCLUDE file.

When you run a command script, RealView Debugger sets the `RVDEBUG_INCLUDE_BASE` environment variable to the location of that command script. Therefore, you can use this environment variable in your command script if required. The environment variable definition exists only for the current debugging session, and changes for each command script that you run.

### Note

The environment variable does not change if the INCLUDE command is used in another command script.

If an error occurs, the debugger behaves as specified by the ERROR command. If a filename extension is not specified, the debugger automatically appends the extension `.inc`.

### Note

If you want to include a batch file when a target is running, you must first enter the wait=off command, then include the batch file:

```> wait=off
> include myfile.inc
```

Your batch file can still include the wait=on command, if required.

The INCLUDE command is normally used to perform repetitive or complex initializations, such as:

• loading and running programs, setting up breakpoints and initial variable definitions

• creating debugger aliases and macros, perhaps for use in later debugging

### Note

The DEFINE command, used to create macros, can only be used in an INCLUDE file.

• running test suites.

You can configure the debugger to load a given INCLUDE file automatically when a target connection is made using the Commands setting of the `Advanced_Information` block for your target.

You can also run script files using the `-inc` argument to RealView Debugger itself.

The INCLUDE command runs asynchronously.

##### Restrictions on the use of INCLUDE

The INCLUDE command is not allowed in a macro.

#### Rules for specifying filenames in the INCLUDE command

Follow these rules when specifying a filename:

• If the filename consists of only alphanumeric characters, slashes, or a period, but the filename does not start with a slash, then you do not have to use quotation marks. For example, `includes/file`.

• Filenames with a leading slash must be in double quotation marks, for example `"/file"`.

• Filenames containing a backslash must be in single quotation marks. For example `'\file'` or `'c:\myfiles\file'`.

Alternatively, you can escape each backslash and use double quotation marks. For example, `"c:\\myfiles\\file"`.

• You can use environment variables to specify paths to a file. For example, if `PATHROOT=C:\MYFILES` and `PATHTEST=TEST1`:

```'\$PATHROOT\\$PATHTEST\test1.c'
```

You can include:

• the filename as part of the second environment variable, and then specify `'\$PATHROOT\\$PATHTEST'`.

• the path separator in the environment variable, and then specify `'\$PATHROOT\$PATHTEST'`.

#### Example

The following example shows how to use INCLUDE:

`INCLUDE "startup.inc"`

Read the file `startup.inc` in the current directory and interpret the contents as RealView Debugger commands. The file `startup.inc` might contain:

```; startup.inc 12/12/00
; Author: J.Doe
;
alias sf*ile =dtfile ;99
alias dub =dump /b
vopen 99
```