finished separating C API from Fortran API

jedwards4b · May 22, 2019 · 74153a0 · 74153a0
1 parent d28b7aa
commit 74153a0
Show file tree

Hide file tree

Showing 215 changed files with 2,171 additions and 7,598 deletions.
diff --git a/doc/source/c_api.txt b/doc/source/c_api.txt
@@ -17,44 +17,28 @@
     - \ref PIO_write_darray_c
     - \ref PIO_setframe_c
   \section utility_c Utility 
-    - \ref PIO_set_hint_grp_c
-    - \ref PIO_setdebuglevel_c
-    - \ref PIO_seterrorhandling_c
+    - \ref PIO_set_hint_c
+    - \ref PIO_error_method_c
     - \ref PIO_get_local_array_size_c
     - \ref PIO_getnumiotasks_c
     - \ref PIO_set_blocksize_c
-  \section netcdf_c NetCDF format specific routines 
+  \section netcdf_c NetCDF-Like Functions
      Also see: http://www.unidata.ucar.edu/software/netcdf/docs/
-     \subsection putget_c Reading/Writing netcdf metadata  
-         - \ref PIO_get_att
-         - \ref PIO_put_att
-         - \ref PIO_get_var
-         - \ref PIO_put_var
-     \subsection utilnc_c Netcdf utility routines
-    - \ref PIO_enddef
-    - \ref PIO_redef
-    - \ref PIO_def_dim 
-    - \ref PIO_def_var
-     \subsection inqnc_c NetCDF file inquiry routines
-    - \ref PIO_inquire
-    - \ref PIO_inq_attname
-    - \ref PIO_inq_att
-    - \ref PIO_inq_attlen
-    - \ref PIO_inquire_variable
-    - \ref PIO_inq_varid
-    - \ref PIO_inq_varname
-    - \ref PIO_inq_vartype
-    - \ref PIO_inq_varndims
-    - \ref PIO_inq_vardimid
-    - \ref PIO_inq_varnatts
-    - \ref PIO_inq_dimid
-    - \ref PIO_inq_dimname
-    - \ref PIO_inq_dimlen
-    - \ref PIO_inq_ndims
-    - \ref PIO_inq_nvars
-    - \ref PIO_inq_natts
-    - \ref PIO_inquire_variable
-    - \ref PIO_inquire_dimension
-    - \ref PIO_inquire_dimension
+     \subsection utilnc_c File Operations
+       - \ref PIO_enddef_c
+       - \ref PIO_redef_c
+     \subsection write_metadata_c Writing Metadata   
+       - \ref PIO_def_dim_c
+       - \ref PIO_def_var_c
+       - \ref PIO_put_att_c
+     \subsection putget_c Reading/Writing Data
+       - \ref PIO_get_var_c
+       - \ref PIO_put_var_c
+     \subsection inqnc_c Learn about Files and Metadata
+       - \ref PIO_inq_c
+       - \ref PIO_get_att_c
+       - \ref PIO_inq_att_c
+       - \ref PIO_inq_var_c
+       - \ref PIO_inq_dim_c
 
 */
diff --git a/docs/_c_a_mexample.html b/docs/_c_a_mexample.html
@@ -107,7 +107,7 @@ <h1><a class="anchor" id="Init"></a>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Sun May 19 2019 07:57:01 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Wed May 22 2019 15:09:23 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

diff --git a/docs/annotated.html b/docs/annotated.html
diff --git a/docs/api.html b/docs/api.html
@@ -5,7 +5,7 @@
 <meta http-equiv="X-UA-Compatible" content="IE=9"/>
 <meta name="generator" content="Doxygen 1.8.13"/>
 <meta name="viewport" content="width=device-width, initial-scale=1"/>
-<title>PIO: PIO user interface</title>
+<title>PIO: PIO Fortran Interface</title>
 <link href="tabs.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="jquery.js"></script>
 <script type="text/javascript" src="dynsections.js"></script>
@@ -61,10 +61,16 @@
 </div><!-- top -->
 <div class="header">
   <div class="headertitle">
-<div class="title">PIO user interface </div>  </div>
+<div class="title">PIO Fortran Interface </div>  </div>
 </div><!--header-->
 <div class="contents">
 <div class="textblock"><p>This is a list of all user interface routines:</p>
+<h1><a class="anchor" id="api_system"></a>
+PIO startup and shutdown routines</h1>
+<ul>
+<li><a class="el" href="group___p_i_o__init.html">PIO_init</a></li>
+<li><a class="el" href="group___p_i_o__finalize.html">PIO_finalize</a> </li>
+</ul>
 <h1><a class="anchor" id="api_fileops"></a>
 PIO file Operations</h1>
 <ul>
@@ -73,12 +79,6 @@ <h1><a class="anchor" id="api_fileops"></a>
 <li><a class="el" href="group___p_i_o__syncfile.html">PIO_syncfile</a></li>
 <li><a class="el" href="group___p_i_o__closefile.html">PIO_closefile</a> </li>
 </ul>
-<h1><a class="anchor" id="api_system"></a>
-PIO startup and shutdown routines</h1>
-<ul>
-<li><a class="el" href="group___p_i_o__init.html">PIO_init</a></li>
-<li><a class="el" href="group___p_i_o__finalize.html">PIO_finalize</a> </li>
-</ul>
 <h1><a class="anchor" id="api_decomp"></a>
 PIO decomposition routines</h1>
 <ul>
@@ -94,7 +94,7 @@ <h1><a class="anchor" id="readwrite"></a>
 <h1><a class="anchor" id="utility"></a>
 Utility routines</h1>
 <ul>
-<li><a class="el" href="group___p_i_o__set__hint.html">PIO_set_hint</a></li>
+<li><a class="el" href="group___p_i_o__set__hint__grp.html">PIO_set_hint</a></li>
 <li><a class="el" href="group___p_i_o__setframe.html">PIO_setframe</a></li>
 <li><a class="el" href="group___p_i_o__advanceframe.html">PIO_advanceframe</a></li>
 <li><a class="el" href="group___p_i_o__setdebuglevel.html">PIO_setdebuglevel</a></li>
@@ -129,7 +129,7 @@ <h2><a class="anchor" id="inqnc"></a>
 <li><a class="el" href="group___p_i_o__inq__attname.html">PIO_inq_attname</a></li>
 <li><a class="el" href="group___p_i_o__inq__att.html">PIO_inq_att</a></li>
 <li><a class="el" href="group___p_i_o__inq__attlen.html">PIO_inq_attlen</a></li>
-<li>PIO_inq_var</li>
+<li><a class="el" href="group___p_i_o__inquire__variable.html">PIO_inquire_variable</a></li>
 <li><a class="el" href="group___p_i_o__inq__varid.html">PIO_inq_varid</a></li>
 <li><a class="el" href="group___p_i_o__inq__varname.html">PIO_inq_varname</a></li>
 <li><a class="el" href="group___p_i_o__inq__vartype.html">PIO_inq_vartype</a></li>
@@ -149,7 +149,7 @@ <h2><a class="anchor" id="inqnc"></a>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Sun May 19 2019 07:57:01 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Wed May 22 2019 15:09:23 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

diff --git a/docs/contributing_code.html b/docs/contributing_code.html
@@ -89,12 +89,209 @@ <h2>Indentation and Spacing</h2>
 <li>
 Indentation as defined by the "linux" style in emacs (see below). </li>
 <li>
-Use spaces around most operators (=+- </li>
+Use spaces around most operators (= + - * /) not pointer or prefix/postfile (* ++ &ndash;) </li>
+<li>
+Spaces after most keywords (if, for, while, etc.) </li>
+<li>
+No spaces after function name. </li>
+</ul>
+<h2>Braces</h2>
+<p>Put braces on their own line, avoiding their use if possible.</p>
+<h2>Documentation</h2>
+<ul>
+<li>
+Every function must be documented using doxygen. </li>
+<li>
+Keep internal functions in separate code files, so that Doxygen can easily build user and development builds of the documentation. </li>
+<li>
+Use the doxygen @ingroup to put public functions in the correct group. </li>
+<li>
+Code must be reasonably documented as to intention. </li>
+<li>
+Documentation quality and quantity are part of code review process. </li>
+<li>
+Document in complete sentences. </li>
+<li>
+Use C (not C++) comment delimiters. </li>
+<li>
+Use the author tag to indicate which programmers have worked on each function. When adding or changing a function in a non-trivial way, programmers should add their name to the end of the list of authors for that function. </li>
+</ul>
+<h2>Emacs</h2>
+<p>Put this in your .emacs file:</p>
+<pre>
+(setq c-default-style "linux"
+          c-basic-offset 4)
+</pre><p>The tab key (used anywhere on the line) will indent a line correctly. M-x indent-region will indent a selected region of code.</p>
+<p>M-x untabify will convert all the tabs in a file to spaces.</p>
+<h2>Code Review</h2>
+<ul>
+<li>
+<p class="startli">All code is subject to review.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">Pull requests will be focused on one issue.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">Pull requests may not be submitted until all tests pass.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">All non-trivial pull requests are associated with a github issue. The issue is where discussion of requirements and implementation details can be worked out.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">Pull requests will be left up on github for about a day. Request more time if you need it and are actively reviewing the code. (Note that pull request can also be reviewed after they are merged, if you miss one).</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">Jim will identify key stakeholders in changed code and ensure they accept code changes.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">Reviewers are open-minded and ready to accept improvements to the library.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">Reviewers will make comments on the pull request. All comments must be resolved.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">If chages are dictated, they happen on the branch, so code reviewers can see the updated code.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">The pull request is only merged when all programmers agree that all issues have been resolved.</p>
+<p class="endli"></p>
+</li>
+</ul>
+<h2>Merge Proceedure</h2>
+<ul>
+<li>
+<p class="startli">Programmers begin work on a feature or fix by branching from develop.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">When a branch is ready, it is submitted to code review.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">When code review is complete, and the changes are approved, the PR is merged into the develop branch.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">Mutliple merges into the develop branch may take place between test cycles. (???)</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">The develop branch is tested automatically by Jenkins.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">The develop branch is tested periodically by CDash (every ~6 hours).</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">After all jenkins and Cdash builds complete successfully, with all tests passing, and no warnings, the PR is merged into master by the integrator.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">Multiple PRs may be merged to master between test cycles. (???)</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">The branch is then deleted by whomever merged it to master.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">The master branch is then tested on Jenkins.</p>
+<p class="endli"></p>
+</li>
+<li>
+<p class="startli">The master branch is tested on CDash. Any test failures and the merge to master will be rolled back.</p>
+<p class="endli"></p>
+</li>
 </ul>
+<h2>Formatting Example</h2>
+<pre>
+/** 
+   @ingroup PIOc_inq_attname
+   The PIO-C interface for the NetCDF function nc_inq_attname.</pre><pre>   This routine is called collectively by all tasks in the communicator 
+   ios.union_comm. For more information on the underlying NetCDF commmand
+   please read about this function in the NetCDF documentation at: 
+   <a href="http://www.unidata.ucar.edu/software/netcdf/docs/group__attributes.html">http://www.unidata.ucar.edu/software/netcdf/docs/group__attributes.html</a></pre><pre>   @param ncid the ncid of the open file, obtained from
+   <a class="el" href="group___p_i_o__open__file__c.html#gae8e01fc5492663b46def2be31a95034c" title="Open an existing file using PIO library. ">PIOc_openfile()</a> or <a class="el" href="group___p_i_o__create__file__c.html#gaed31e065901c964d4224b3db61a30d5e" title="Create a new file using pio. ">PIOc_createfile()</a>.
+   @param varid the variable ID.
+   @param attnum the attribute ID.
+   @return PIO_NOERR for success, error code otherwise.  See PIOc_Set_File_Error_Handling
+ */
+int <a class="el" href="pio_8h.html#aa7d8b173e8bba7544c042301877082a0" title="The PIO-C interface for the NetCDF function nc_inq_attname. ">PIOc_inq_attname(int ncid, int varid, int attnum, char *name)</a> 
+{
+    <a class="el" href="structiosystem__desc__t.html" title="IO system descriptor structure. ">iosystem_desc_t</a> *ios;  /* Pointer to io system information. */
+    <a class="el" href="structfile__desc__t.html" title="File descriptor structure. ">file_desc_t</a> *file;     /* Pointer to file information. */
+    int ierr = PIO_NOERR;  /* Return code from function calls. */
+    int mpierr = MPI_SUCCESS, mpierr2;  /* Return code from MPI function codes. */</pre><pre>    LOG((1, "PIOc_inq_attname ncid = %d varid = %d attnum = %d", ncid, varid,
+         attnum));</pre><pre>    /* Find the info about this file. */
+    if (!(file = pio_get_file_from_id(ncid)))
+        return PIO_EBADID;
+    ios = file-&gt;iosystem;</pre><pre>    /* If async is in use, and this is not an IO task, bcast the parameters. */
+    if (ios-&gt;async_interface)
+    {
+        if (!ios-&gt;ioproc)
+        {
+            int msg = PIO_MSG_INQ_ATTNAME;
+            char name_present = name ? true : false;</pre><pre>            if(ios-&gt;compmaster) 
+                mpierr = MPI_Send(&amp;msg, 1,MPI_INT, ios-&gt;ioroot, 1, ios-&gt;union_comm);</pre><pre>            if (!mpierr)
+                mpierr = MPI_Bcast(&amp;ncid, 1, MPI_INT, ios-&gt;compmaster, ios-&gt;intercomm);
+            if (!mpierr)
+                mpierr = MPI_Bcast(&amp;varid, 1, MPI_INT, ios-&gt;compmaster, ios-&gt;intercomm);
+            if (!mpierr)
+                mpierr = MPI_Bcast(&amp;attnum, 1, MPI_INT, ios-&gt;compmaster, ios-&gt;intercomm);
+            if (!mpierr)
+                mpierr = MPI_Bcast(&amp;name_present, 1, MPI_CHAR, ios-&gt;compmaster, ios-&gt;intercomm);
+        }</pre><pre>        /* Handle MPI errors. */
+        if ((mpierr2 = MPI_Bcast(&amp;mpierr, 1, MPI_INT, ios-&gt;comproot, ios-&gt;my_comm)))
+            check_mpi(file, mpierr2, __FILE__, __LINE__);
+        if (mpierr)
+            return check_mpi(file, mpierr, __FILE__, __LINE__);
+    }</pre><pre>    /* If this is an IO task, then call the netCDF function. */
+    if (ios-&gt;ioproc)
+    {
+#ifdef _PNETCDF
+        if (file-&gt;iotype == PIO_IOTYPE_PNETCDF)
+            ierr = ncmpi_inq_attname(file-&gt;fh, varid, attnum, name);
+#endif /* _PNETCDF */
+#ifdef _NETCDF
+        if (file-&gt;iotype != PIO_IOTYPE_PNETCDF &amp;&amp; file-&gt;do_io)
+            ierr = nc_inq_attname(file-&gt;fh, varid, attnum, name);
+#endif /* _NETCDF */
+        LOG((2, "PIOc_inq_attname netcdf call returned %d", ierr));
+    }</pre><pre>    /* Broadcast and check the return code. */
+    if ((mpierr = MPI_Bcast(&amp;ierr, 1, MPI_INT, ios-&gt;ioroot, ios-&gt;my_comm)))
+    {
+        check_mpi(file, mpierr, __FILE__, __LINE__);            
+        return PIO_EIO;
+    }
+    check_netcdf(file, ierr, __FILE__, __LINE__);</pre><pre>    /* Broadcast results to all tasks. Ignore NULL parameters. */
+    if (!ierr)
+        if (name)
+        {
+            int namelen = strlen(name);
+            if ((mpierr = MPI_Bcast(&amp;namelen, 1, MPI_INT, ios-&gt;ioroot, ios-&gt;my_comm)))
+                check_mpi(file, mpierr, __FILE__, __LINE__);
+            if ((mpierr = MPI_Bcast((void *)name, namelen + 1, MPI_CHAR, ios-&gt;ioroot,
+                                    ios-&gt;my_comm)))
+                check_mpi(file, mpierr, __FILE__, __LINE__);
+        }</pre><pre>    return ierr;
+}
+</pre><h2>Further Information</h2>
+<p>For style issues not already covered in this document, see this <a href="https://www.kernel.org/doc/Documentation/CodingStyle">style guide</a>.</p>
+<p><em>Last updated: 05-16-2016</em> </p>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Sun May 19 2019 07:57:01 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Wed May 22 2019 15:09:23 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

diff --git a/docs/decomp.html b/docs/decomp.html
@@ -94,7 +94,7 @@ <h1><a class="anchor" id="SUBSETREARR"></a>
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Sun May 19 2019 07:57:01 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Wed May 22 2019 15:09:23 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>

diff --git a/docs/deprecated.html b/docs/deprecated.html
@@ -77,7 +77,7 @@
 </div></div><!-- contents -->
 <!-- start footer part -->
 <hr class="footer"/><address class="footer"><small>
-Generated on Sun May 19 2019 07:57:01 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
+Generated on Wed May 22 2019 15:09:23 for PIO by &#160;<a href="http://www.doxygen.org/index.html">
 <img class="footer" src="doxygen.png" alt="doxygen"/>
 </a> 1.8.13
 </small></address>