# Advanced tips and tricks

This page covers some of the really low-level detail that should not concern most users,
but advanced users may find helpful.

.. _java_options:

## Java options

Java provides a generic framework for changing the run-time characteristics of
Java applications such as RiskScape. For example, you can set the locale that the program uses
(for :ref:`i18n`) or change how things like garbage collection behave.

These settings are called Java *system properties* and are typically set using `-Dproperty=value`. 
There is a wide range of potential settings that can be configured for
[Windows](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/java.html)
or [Linux](https://docs.oracle.com/javase/8/docs/technotes/tools/unix/java.html).

You can change Java system properties by setting one of the following environment variables:
- `JAVA_TOOL_OPTIONS` - note that these settings apply to all Java programs, not just RiskScape.
- `RISKSCAPE_OPTS` - these settings only apply to RiskScape.

In addition, Java also supports `_JAVA_OPTIONS` and `JVM_OPTS` (Linux) and `JAVA_OPTS` (Windows).
However, there is less universal support for these latter environment variables, as they tend to
be either platform-specific or undocumented.

As there are multiple different ways of setting Java system properties, the following precedence
takes effect:
1. `_JAVA_OPTIONS`.
2. `RISKSCAPE_OPTS`.
3. Any system properties that RiskScape might set by default.
4. `JAVA_TOOL_OPTIONS`.

.. warning::
  We recommend you talk to a RiskScape developer first before experimenting, as changing
  Java system properties could have a detrimental effect on RiskScape behaviour.

## Windows quirks

### Using quotes in the terminal

Generally, it's recommended to always use double-quotes when specifying parameters for the `riskscape model run` command.

However, Windows users _may_ experience annoying terminal behaviour where the quote mark won't be displayed immediately
after it is typed. To check if this problem affects you:
1. Open the Windows terminal.
2. Type the quote character, i.e. `'` or `Shift` and `'`.
3. If nothing is displayed, press the space bar. The quote mark should now be visible.

This appears to be a [known issue](https://answers.microsoft.com/en-us/windows/forum/all/cant-type-quotation-marks/4fbb77b6-461c-4b06-bed2-5d9d67e706ea)
on Windows.

Anecdotally, we have seen this problem resolve when unnecessary additional language packs were uninstalled.
To check what language packs you currently have installed, select _Settings_ -> _Time and Language_ -> _Language_
and then look under 'Preferred languages'.

.. _shell_scripting:

## Shell scripting

For an example of using RiskScape to loop over hazard files, see :ref:`model_batch`.
If the `riskscape model batch` command is not quite right for you, then you may be able to use *shell scripting* to run
RiskScape commands repeatedly.

Your terminal will usually support some sort of `for` loop, that will let you iterate over a set of values.
The syntax for this will vary depending on what operating system and terminal you are using.

For example, in the Windows Command Prompt, the following statement will loop through a set of GeoTIFFs in the `data` directory,
and use them as the input hazard-layer for your model.

```none
for %f in (data\*.tif) do riskscape model run MODEL_NAME -p "input-hazards.layer=%f" --output=output\%~nf
```

Wheres on Linux, the following bash code will do the same thing.

```bash
for f in $(ls data/*.tif) ; do riskscape model run MODEL_NAME -p "input-hazards.layer=$f" --output=output/$(basename $f) ; done
```

### Batch scripts

Getting the `for` loop command right can be a little tricky.
An alternative approach is to save the commands to a script file and then run the file as needed.
On Windows, this is called a [batch file](https://en.wikipedia.org/wiki/Batch_file).

Below is an example of a Windows batch file that runs every model in the :ref:`getting-started` tutorial project.
The `::` lines are comments that explain what the script does.

```batch
:: Make sure riskscape is present on our PATH
:: (update this to match your RiskScape installation directory)
set PATH=%PATH%;C:\RiskScape\riskscape\bin

:: change to the directory that contains our project file
cd C:\RiskScape_Projects\getting-started

:: define in a variable the models in our project that we want to run
set models_to_run=basic-exposure exposure-reporting exposure-by-region

:: loop through the models specified and run each one
for %%x in (%models_to_run%) do (
    call echo Running: riskscape model run %%x
    call riskscape model run %%x
    )

:: don't close the terminal when we're done
echo DONE!
pause
```

If things are getting repetitive, you can *nest* multiple ``for`` loops together.
For example, the following batch file snippet would run *all* GeoTIFFs in a directory
through a *series* of different models.

```batch
for %%f in (data\*.tif) do (
    for %%x in (%models_to_run%) do (
        call echo Running: riskscape model run %%x hazard=%%f
        call riskscape model run %%x -p "input-hazards.layer=%%f" --output=output\%%x\%%~nf
    )
)
```

.. note::
    To avoid nested ``for`` loops, you could alternatively combine the ``riskscape model batch``
    command with a single ``for`` loop. This would let you iterate through multiple different
    things, without the batch file getting too complicated.

.