# Upgrading STICS XML files

    library(SticsRFiles)

The XML files structure has changed between STICS version 9.2 and versions 10.X.Y and a transformation is mandatory.

So, to avoid difficulties and errors with manual XML files modifications, functionalities have been developed to do so automatically.

One can either transform a complete workspace directory at once or each kind of file individually.

## Upgrading a whole workspace

In that case, a workspace adapted to the new version is recreated.

So, apart from the XML files, some other files as outputs definition files (*.mod), weather files attached to USMs and also observation files (named with the USM name, *.obs) are copied to the new workspace.

    workspace <- "/path/to/workspace/dir/V9.2"
    out_dir <- "/path/to/out/dir/V10.2.0"
    javastics <- "/path/to/JavaSTICS-1.41-stics-9.2"
    upgrade_workspace_xml(workspace = workspace, javastics = javastics, out_dir = out_dir)

Here is the output display indicating the treated files:

    Upgrading files from version V9.2 to V10.2.0
    From:  /path/to/workspace/dir/V9.2
    To:  /path/to/out/dir/V10.2.0
    -----------------------------------
    param_gen.xml
    param_new_form.xml
    usms.xml
    sols.xml
    *_sta.xml
    *_ini.xml
    *_tec.xml
    Copying *.mod files.
    Copying *.obs files.
    Copying weather files.
    *_plt.xml
    -----------------------------------
    Files upgrade and copy is complete.

## Upgrading a specific file kind

For each kind of file, a specific function is to be used for upgrading its format.

- `usms.xml` : upgrade_usms_xml
- `*_ini.xml` files: upgrade_ini_xml
- `param_gen.xml`: upgrade_param_gen_xml
- `param_newform.xml`: upgrade_param_newform_xml
- `*_plt.xml` files: upgrade_plt_xml
- `sols.xml`: upgrade_sols_xml
- `*_sta.xml` files: upgrade_sta_xml
- `*_tec.xml` files: upgrade_tec_xml

The input arguments of these functions may vary, refer to each function help for details about its use.

Sometimes, general parameter files are needed as function inputs because of parameters or options codes movement to specific files.

For example, the `usms.xml` file is to be upgraded as follows:

    usms_path <- "/path/to/workspace/dir/V9.2/usms.xml"
    out_dir <- "/path/to/workspace/dir/V10.2.0"
    param_gen_path <- "/path/to/JavaSTICS-1.41-stics-9.2/config/param_gen.xml"
    upgrade_usms_xml(file = usms_path, param_gen_file = param_gen_path, out_dir = out_dir)