scr: update docs to document return value in Fortran failure case

doc/rst/users/api.rst

@@ -124,6 +124,7 @@ the call allocates and returns a pointer to a string holding the value of the pa
 The caller is responsible for calling :code:`free` to release the returned string.
 If the parameter has not been set, :code:`NULL` is returned.
 For Fortran applications, the value is returned as a string in the :code:`VAL` argument.
+If the parameter has not been set, :code:`IERROR` is set to :code:`SCR_FAILURE` in Fortran.
 
 To unset a value, one specifies the parameter name with an empty value
 in the form of a :code:`key=` string as the :code:`config` argument.

src/scr.h

@@ -22,6 +22,7 @@ extern "C" {
 
 /* constants returned from SCR functions for success and failure */
 #define SCR_SUCCESS (0)
+#define SCR_FAILURE (1)
 
 /* maximum characters in a filename returned by SCR */
 #define SCR_MAX_FILENAME 1024

src/scr_util.h

@@ -33,8 +33,6 @@
 #ifndef SCR_UTIL_H
 #define SCR_UTIL_H
 
-#define SCR_FAILURE (1)
-
 #include <stdlib.h>
 #include <stdint.h>
 #include <stdarg.h>

src/scrf.c

@@ -158,13 +158,13 @@ FORTRAN_API void FORT_CALL scr_config_(char* cfg FORT_MIXED_LEN(cfg_len),
   /* convert name from a Fortran string to C string */
   char cfg_tmp[SCR_MAX_FILENAME];
   if (scr_fstr2cstr(cfg, cfg_len, cfg_tmp, sizeof(cfg_tmp)) != 0) {
-    *ierror = !SCR_SUCCESS;
+    *ierror = SCR_FAILURE;
     return;
   }
 
   const char *val_tmp = SCR_Config(cfg_tmp);
   if (!val_tmp) {
-    *ierror = !SCR_SUCCESS;
+    *ierror = SCR_FAILURE;
     return;
   }
   /* TODO: there is a memory leak here. scr_config, when called to get a value
@@ -179,7 +179,7 @@ FORTRAN_API void FORT_CALL scr_config_(char* cfg FORT_MIXED_LEN(cfg_len),
 
   /* convert val to Fortran string */
   if (scr_cstr2fstr(val_tmp, val, val_len) != 0) {
-    *ierror = !SCR_SUCCESS;
+    *ierror = SCR_FAILURE;
     return;
   }
 
@@ -200,7 +200,7 @@ FORTRAN_API void FORT_CALL scr_have_restart_(int* flag, char* name FORT_MIXED_LE
   if (*flag) {
     /* convert name to Fortran string */
     if (scr_cstr2fstr(name_tmp, name, name_len) != 0) {
-      *ierror = !SCR_SUCCESS;
+      *ierror = SCR_FAIULRE;
       return;
     }
   }
@@ -216,7 +216,7 @@ FORTRAN_API void FORT_CALL scr_start_restart_(char* name FORT_MIXED_LEN(name_len
 
   /* convert name to Fortran string */
   if (scr_cstr2fstr(name_tmp, name, name_len) != 0) {
-    *ierror = !SCR_SUCCESS;
+    *ierror = SCR_FAIULRE;
     return;
   }
 
@@ -262,7 +262,7 @@ FORTRAN_API void FORT_CALL scr_start_output_(char* name FORT_MIXED_LEN(name_len)
   /* convert name from a Fortran string to C string */
   char name_tmp[SCR_MAX_FILENAME];
   if (scr_fstr2cstr(name, name_len, name_tmp, sizeof(name_tmp)) != 0) {
-    *ierror = !SCR_SUCCESS;
+    *ierror = SCR_FAIULRE;
     return;
   }
 
@@ -290,7 +290,7 @@ FORTRAN_API void FORT_CALL scr_route_file_(char* name FORT_MIXED_LEN(name_len),
   /* convert filename from a Fortran string to C string */
   char name_tmp[SCR_MAX_FILENAME];
   if (scr_fstr2cstr(name, name_len, name_tmp, sizeof(name_tmp)) != 0) {
-    *ierror = !SCR_SUCCESS;
+    *ierror = SCR_FAIULRE;
     return;
   }
 
@@ -300,7 +300,7 @@ FORTRAN_API void FORT_CALL scr_route_file_(char* name FORT_MIXED_LEN(name_len),
 
   /* convert filename from C to Fortran string */
   if (scr_cstr2fstr(file_tmp, file, file_len) != 0) {
-    *ierror = !SCR_SUCCESS;
+    *ierror = SCR_FAIULRE;
     return;
   }
 
@@ -316,7 +316,7 @@ FORTRAN_API void FORT_CALL scr_current_(char* name FORT_MIXED_LEN(name_len), int
   /* convert name from a Fortran string to C string */
   char name_tmp[SCR_MAX_FILENAME];
   if (scr_fstr2cstr(name, name_len, name_tmp, sizeof(name_tmp)) != 0) {
-    *ierror = !SCR_SUCCESS;
+    *ierror = SCR_FAIULRE;
     return;
   }
 
@@ -330,7 +330,7 @@ FORTRAN_API void FORT_CALL scr_drop_(char* name FORT_MIXED_LEN(name_len), int* i
   /* convert name from a Fortran string to C string */
   char name_tmp[SCR_MAX_FILENAME];
   if (scr_fstr2cstr(name, name_len, name_tmp, sizeof(name_tmp)) != 0) {
-    *ierror = !SCR_SUCCESS;
+    *ierror = SCR_FAIULRE;
     return;
   }
 
@@ -344,7 +344,7 @@ FORTRAN_API void FORT_CALL scr_delete_(char* name FORT_MIXED_LEN(name_len), int*
   /* convert name from a Fortran string to C string */
   char name_tmp[SCR_MAX_FILENAME];
   if (scr_fstr2cstr(name, name_len, name_tmp, sizeof(name_tmp)) != 0) {
-    *ierror = !SCR_SUCCESS;
+    *ierror = SCR_FAIULRE;
     return;
   }