== Backward incompatible changes in XIOS 2.0 ==

Although we try to limit them as much as possible, there are some backward incompatible changes that you may notice when migrating from XIOS 1.0 to XIOS 2.0.

This document lists all those changes at the time it was written and might not always be up-to-date due to XIOS 2.0 still being in development.

- the `type` attribute of the `variable` object is now more strictly checked. It must be one of:
  - `bool`
  - `int` or `int32`
  - `int16`
  - `int64`
  - `float`
  - `double`
  - `string`.

  For example, `<variable id="my_attribute2" type="integer" >10</variable>` will become `<variable id="my_attribute2" type="int" >10</variable>` and `<variable id="print_file" type="boolean">true</variable>` will become `<variable id="print_file" type="bool">true</variable>`.
- Calendar related attributes (`calendar_type`, `timestep`, `start_date`, `time_origin`) have been moved from the `context` object to a new child object `calendar`.

  The following excerpt from a configuration file:
  {{{
    <context id="test" calendar_type="Gregorian" start_date="2012-03-01 15:00:00" time_origin="2012-02-29 15:00:00">
    ...
    </context>
  }}}
  will become:
  {{{
    <context id="test">
      <calendar type="Gregorian" start_date="2012-03-01 15:00:00" time_origin="2012-02-29 15:00:00" />
    ...
    </context>
  }}}

- Be careful to the following changes related to the calendar initialization:
    - XIOS now requires that the calendar type is decided once and for all, either in the configuration file or the Fortran interface.
    - the start date and time origin cannot be defined before the calendar type has been decided.
    - by default the start date and the time origin are defined as `0000-01-01 00:00:00`. If the start date is set but the time origin is not, the time origin is not automatically set to be equal to the start date.

- The Fortran interface has been modified to reflect the changes made to the calendar definition in the configuration file and a new type `xios_date` must now be used to manipulate the attributes corresponding to dates (`start_date`, `time_origin`).

  The following code:
  {{{
  PROGRAM test
    USE xios
    ...
    CALL xios_set_context_attr("test",calendar_type="Gregorian")
    CALL xios_set_context_attr("test",start_date="2000-01-01 00:00:00")
    CALL xios_set_context_attr("test",time_origin="1999-01-01 15:00:00")
    ...
  END PROGRAM test
  }}}
  will become:
  {{{
  PROGRAM test
    USE xios
    ...
    TYPE(xios_date) :: start_date, time_origin
    ...
    CALL xios_get_handle("test",ctx_hdl)
    CALL xios_set_current_context(ctx_hdl)
    ...
    CALL xios_define_calendar("Gregorian")
    start_date = xios_date(2000, 01, 01, 00, 00, 00)
    CALL xios_set_start_date(start_date)
    time_origin = xios_date(1999, 01, 01, 15, 00, 00)
    CALL xios_set_time_origin(time_origin)
    ...
  END PROGRAM test
  }}}
  or
  {{{
  PROGRAM test
    USE xios
    ...
    TYPE(xios_date) :: start_date, time_origin
    ...
    CALL xios_get_handle("test",ctx_hdl)
    CALL xios_set_current_context(ctx_hdl)
    ...
    start_date = xios_date(2000, 01, 01, 00, 00, 00)
    time_origin = xios_date(1999, 01, 01, 15, 00, 00)
    CALL xios_define_calendar("Gregorian", start_date=start_date, time_origin=time_origin)
    ...
  END PROGRAM test
  }}}

- attributes corresponding to a duration should now be manipulated using the `xios_duration` type when using the Fortran interface. Affected attributes are:
  - `timestep` in `calendar` objects (previously in the `context` objects)
  - `freq_op` and `freq_offset` in `field` objects
  - `output_freq`, `sync_freq` and `split_freq` in `file` objects.

  Note that the old `xios_time` type have been removed.

  The following code:
  {{{
  PROGRAM test
    USE xios
    ...
    TYPE(xios_time) :: dtime
    ...
    CALL xios_get_handle("test",ctx_hdl)
    CALL xios_set_current_context(ctx_hdl)
    ...
    dtime%second=3600
    CALL xios_set_timestep(dtime)
    ...
  END PROGRAM test
  }}}
  will become:
  {{{
  PROGRAM test
    USE xios
    ...
    TYPE(xios_duration) :: dtime
    ...
    CALL xios_get_handle("test",ctx_hdl)
    CALL xios_set_current_context(ctx_hdl)
    ...
    dtime%second=3600
    CALL xios_set_timestep(dtime)
    ...
  END PROGRAM test
  }}}