added get and set state to sidl, documentation still to do

AUTHORS.rst

@@ -24,6 +24,7 @@ Contributors
 * Greg Tucker
 * Ben van Werkhoven
 * Martijn Visser
+* Rolf Hut
 
 If you have contributed to the BMI project and your name is missing,
 please send an email to the coordinators, or open a pull request

bmi.sidl

@@ -1,7 +1,7 @@
 //
 // The Basic Model Interface (BMI)
 //
-package csdms version 2.0 {
+package csdms version 2.1 {
   interface bmi {
 
     // Initialize, run, finalize (IRF)
@@ -37,11 +37,15 @@ package csdms version 2.0 {
     int get_value_ptr(in string name, out array<> dest_ptr);
     int get_value_at_indices(in string name, in array<> dest,
         in array<int, 1> inds);
+    int get_state(out string state);
+    int get_state_ptr(out array<> dest_ptr);
 
     // Setters
     int set_value(in string name, in array<> src);
     int set_value_at_indices(in string name, in array<int, 1> inds,
         in array<> src);
+    int set_state(in string state);
+    int set_state_ptr(in array<> src);
 
     // Grid information
     int get_grid_rank(in int grid, out int rank);

docs/source/bmi.getter_setter.rst

@@ -79,7 +79,6 @@ even if the model's state has changed.
 
 [:ref:`getter_setter_funcs` | :ref:`basic_model_interface`]
 
-
 .. _get_value_at_indices:
 
 *get_value_at_indices*
@@ -105,6 +104,31 @@ Additionally,
 
 [:ref:`getter_setter_funcs` | :ref:`basic_model_interface`]
 
+.. _get_state:
+
+*get_state*
+...........
+
+.. code-block:: java
+
+   /* SIDL */
+   int get_state(out string);
+
+The `get_state` function collects all information that forms the
+state of the model and presents that as a single string. The formatting
+of the output string is wholly upon the modeller. Best practices include
+formatting as NETCDF or JSON.
+
+**Implementation notes**
+
+* In C++ and Java, `get_state` is a void function.
+* Depending on how a model is written, the state may not be
+  accessible until after the call to :ref:`initialize`. Likewise, the
+  state may not be accessible after calling :ref:`finalize`.
+* In C and Fortran, an integer status code indicating success (zero) or failure
+  (nonzero) is returned.
+
+[:ref:`getter_setter_funcs` | :ref:`basic_model_interface`]
 
 .. _set_value:
 

docs/source/bmi.spec.rst

@@ -115,8 +115,12 @@ grouped by functional category.
    :ref:`get_value`                Get a copy of values of a given variable.
    :ref:`get_value_ptr`            Get a reference to the values of a given variable.
    :ref:`get_value_at_indices`     Get variable values at specific locations.
+   :ref:`get_state`                Get all the variables that together form the state of the model.
+   :ref:`get_state_pr`             Get a reference to the value of the state.
    :ref:`set_value`                Set the values of a given variable.
    :ref:`set_value_at_indices`     Set the values of a variable at specific locations.
+   :ref:`set_state`                Set all the variables that together form the state of the model.
+   :ref:`set_state_pr`             Set the state by providing a reference.
    :ref:`get_grid_rank`            Get the number of dimensions of a computational grid.
    :ref:`get_grid_size`            Get the total number of elements of a computational grid.
    :ref:`get_grid_type`            Get the grid type as a string.