[svn-r9256] Purpose:

   Update release_docs/RELEASE.txt to describe options for dealing
   with installations which insert extra text in output, thereby
   breaking tests which function by comparing output with an exemplar.


Description:

   See above.


Solution:

   Add discussion of this possible problem, and listed two possible
   solutions:

   1) "setenv HDF5_Make_Ignore yes" and then score "failed" tests
      by hand.

   2) Use the RUNSERIAL environment variable to use a filter script
      to filter out the extra text.


Platforms tested:

   No testing needed.


Misc. update:

1 files changed, 57 insertions, 0 deletions

diff --git a/release_docs/RELEASE.txt b/release_docs/RELEASE.txt
index 6dc7761..7fb7fc0 100644
--- a/release_docs/RELEASE.txt
+++ b/release_docs/RELEASE.txt
@@ -629,3 +629,60 @@ ftp://hdf.ncsa.uiuc.edu/pub/outgoing/hdf5/hdf5-1.6.2/F90_source_for_Crays
 
 * Information about building with PGI and Intel compilers is available in
   INSTALL file sections 5.7 and 5.8
+
+* On at least one system, (SDSC DataStar), the scheduler (in this case
+  LoadLeveler) sends job status updates to standard error when you run 
+  any executable that was compiled with the parallel compilers.
+
+  This causes problems when running "make check" on parallel builds, as 
+  many of the tool tests function by saving the output from test runs,
+  and comparing it to an exemplar.  
+
+  The best solution is to reconfigure the target system so it no longer
+  inserts the extra text.  However, this may not be practical.
+
+  In such cases, one solution is to "setenv HDF5_Make_Ignore yes" prior to 
+  the configure and build.  This will cause "make check" to continue after 
+  detecting errors in the tool tests.  However, in the case of SDSC DataStar,
+  it also leaves you with some 150 "failed" tests to examine by hand.
+
+  A second solution is to write a script to run serial tests and filter
+  out the text added by the scheduler.  A sample script used on SDSC
+  DataStar is given below, but you will probably have to customize it 
+  for your installation.  
+
+  Observe that the basic idea is to insert the script as the first item 
+  on the command line which executes the the test.  The script then 
+  executes the test and filters out the offending text before passing
+  it on.
+
+        #!/bin/csh
+
+        set STDOUT_FILE=~/bin/serial_filter.stdout
+        set STDERR_FILE=~/bin/serial_filter.stderr
+
+        rm -f $STDOUT_FILE $STDERR_FILE
+
+        ($* > $STDOUT_FILE) >& $STDERR_FILE
+
+	set RETURN_VALUE=$status
+
+        cat $STDOUT_FILE
+
+        tail +3 $STDERR_FILE
+
+	exit $RETURN_VALUE
+
+  You get the HDF make files and test scipts to execute your filter script
+  by setting the environment variable "RUNSERIAL" to the full path of the 
+  script prior to running configure for parallel builds.  Remember to 
+  "unsetenv RUNSERIAL" before running configure for a serial build.
+
+  Note that the RUNSERIAL environment variable exists so that we can 
+  can prefix serial runs as necessary on the target system.  On DataStar,
+  no prefix is necessary.  However on an MPICH system, the prefix might
+  have to be set to something like "/usr/local/mpi/bin/mpirun -np 1" to
+  get the serial tests to run at all.
+
+  In such cases, you will have to include the regular prefix in your
+  filter script.