[svn-r8765] Purpose: New feature and its test.

Description:  Added new API H5Fget_name and new test program called filename.c.  This function
returns the name of the file by object ID(file, group, dataset, named datatype, and attribute)
which belongs to the file.


Platforms tested:  h5committest and fuss.

Misc. update:  MANIFEST and RELEASE.txt

10 files changed, 228 insertions, 5 deletions

diff --git a/MANIFEST b/MANIFEST
index bb55163..92583fb 100644
--- a/MANIFEST
+++ b/MANIFEST
@@ -971,6 +971,7 @@
 ./test/error_test.c
 ./test/err_compat.c
 ./test/file_handle.c
+./test/filename.c
 ./test/fill_old.h5
 ./test/fillval.c
 ./test/flush1.c
diff --git a/c++/src/H5File.h b/c++/src/H5File.h
index e19f3f8..bb20643 100644
--- a/c++/src/H5File.h
+++ b/c++/src/H5File.h
@@ -74,7 +74,7 @@ class H5_DLLCPP H5File : public IdComponent, public CommonFG {
 
         // Retrieves the file size of an opened file.
         haddr_t getFileSize() const;
-        
+
 	// Reopens this file
 	void reopen();
 
diff --git a/c++/test/tfile.cpp b/c++/test/tfile.cpp
index 299986b..9dc6127 100644
--- a/c++/test/tfile.cpp
+++ b/c++/test/tfile.cpp
@@ -62,6 +62,9 @@ using namespace H5;
 #define KB                      1024
 #define FILE4                   "tfile4.h5"
 
+#define FILE5                   "tfile5.h5"
+#define NAME_LEN                64
+
 
 /*-------------------------------------------------------------------------
  * Function:    test_file_create
diff --git a/release_docs/RELEASE.txt b/release_docs/RELEASE.txt
index 3be733e..63a3764 100644
--- a/release_docs/RELEASE.txt
+++ b/release_docs/RELEASE.txt
@@ -44,6 +44,9 @@ New Features
 
     Library:
     --------
+        - A new API function H5Fget_name was added.  It returns the name
+            of the file by object(file, group, data set, named data type,
+            attribute) ID.  SLU - 2004/06/29
         - A new API function H5Fget_filesize was added.  It returns the
             actual file size of the opened file.  SLU - 2004/06/24
 	- New Feature of Data transformation is added.  AKC - 2004/05/03.
diff --git a/src/H5F.c b/src/H5F.c
index 72c1265..2dc7880 100644
--- a/src/H5F.c
+++ b/src/H5F.c
@@ -4743,3 +4743,55 @@ H5Fget_filesize(hid_t file_id)
 done:
     FUNC_LEAVE_API(ret_value)
 } /* end H5Fget_filesize() */
+
+
+/*-------------------------------------------------------------------------
+ * Function:    H5Fget_name
+ *
+ * Purpose:     Gets the name of the file to which object OBJ_ID belongs.
+ *              If `name' is non-NULL then write up to `size' bytes into that
+ *              buffer and always return the length of the entry name.
+ *              Otherwise `size' is ignored and the function does not store the name,
+ *              just returning the number of characters required to store the name.
+ *              If an error occurs then the buffer pointed to by `name' (NULL or non-NULL)
+ *              is unchanged and the function returns a negative value.
+ *              
+ * Return:      Success:        The length of the file name 
+ *              Failure:        Negative
+ *
+ * Programmer:  Raymond Lu
+ *              June 29, 2004
+ *
+ * Modifications:
+ *
+ *-------------------------------------------------------------------------
+ */
+ssize_t
+H5Fget_name(hid_t obj_id, char *name/*out*/, size_t size)
+{
+    H5G_entry_t   *ent;       /*symbol table entry */
+    size_t        len=0;
+    ssize_t       ret_value;
+
+    FUNC_ENTER_API (H5Fget_name, FAIL);
+    H5TRACE3("Zs","ixz",obj_id,name,size);
+
+    /* get symbol table entry */
+    if((ent = H5G_loc(obj_id))==NULL)
+         HGOTO_ERROR(H5E_ARGS, H5E_BADVALUE, FAIL, "not a valid object ID")
+
+    len = HDstrlen(ent->file->name);
+
+    if(name) {
+        HDstrncpy(name, ent->file->name, MIN(len+1,size));
+        if(len >= size)
+            name[size-1]='\0';
+    } /* end if */
+
+    /* Set return value */
+    ret_value=(ssize_t)len;
+
+done:
+    FUNC_LEAVE_API(ret_value);
+} /* end H5Fget_name() */
+
diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h
index 911bdff..c372130 100644
--- a/src/H5Fpublic.h
+++ b/src/H5Fpublic.h
@@ -114,6 +114,7 @@ H5_DLL herr_t H5Fmount(hid_t loc, const char *name, hid_t child, hid_t plist);
 H5_DLL herr_t H5Funmount(hid_t loc, const char *name);
 H5_DLL hssize_t H5Fget_freespace(hid_t file_id);
 H5_DLL haddr_t H5Fget_filesize(hid_t file_id);
+H5_DLL ssize_t H5Fget_name(hid_t obj_id, char *name, size_t size);
 
 #ifdef __cplusplus
 }
diff --git a/src/H5I.c b/src/H5I.c
index e538f52..35d276e 100644
--- a/src/H5I.c
+++ b/src/H5I.c
@@ -2022,7 +2022,9 @@ H5I_find_id(hid_t id)
  *
  * Purpose: Gets a name of an object from its ID. 
  *
- * Return: Success: 0, Failure: -1
+ * Return: Success: The length of name.
+ * 
+ *         Failure: -1
  *
  * Programmer: Pedro Vicente, pvn@ncsa.uiuc.edu
  *
diff --git a/src/H5MPprivate.h b/src/H5MPprivate.h
index 126194e..24d709e 100644
--- a/src/H5MPprivate.h
+++ b/src/H5MPprivate.h
@@ -131,6 +131,7 @@
 #define color_H5Funmount "red"
 #define color_H5Fget_freespace "red"
 #define color_H5Fget_filesize "red"
+#define color_H5Fget_name "red"
 
 #define color_H5Gcreate "red"
 #define color_H5Gopen "red"
diff --git a/test/Makefile.in b/test/Makefile.in
index 78e25d1..7121290 100644
--- a/test/Makefile.in
+++ b/test/Makefile.in
@@ -31,7 +31,7 @@ TEST_PROGS=testhdf5 lheap ohdr stab gheap hyperslab istore bittests dtypes
            dsets cmpd_dset extend external links unlink big mtime fillval mount \
            flush1 flush2 enum gass_write gass_read gass_append set_extent       \
            srb_write srb_append srb_read ttsafe stream_test getname file_handle \
-           ntypes dangle dtransform
+           ntypes dangle dtransform filename
            
 ## Test programs for Error API.  Only compile them but let testerror.sh run 
 ## them to compare the output error messages with standard ones.  'make check'
@@ -68,7 +68,7 @@ MOSTLYCLEAN=cmpd_dset.h5 compact_dataset.h5 dataset.h5 extend.h5 istore.h5   \
             getname.h5 getname[1-3].h5 sec2_file.h5                          \
             family_file000[0-3][0-9].h5 multi_file-[rs].h5 core_file         \
             new_move_[ab].h5 ntypes.h5 dangle.h5 error_test.h5 err_compat.h5 \
-            dtransform.h5 test_filters.h5
+            dtransform.h5 test_filters.h5 get_file_name.h5
 
 CLEAN=$(TIMINGS)
 
@@ -87,7 +87,7 @@ TEST_SRC=big.c bittests.c cmpd_dset.c dsets.c dtypes.c extend.c              \
          ttsafe_cancel.c ttsafe_acreate.c gass_write.c gass_read.c           \
          gass_append.c srb_read.c srb_write.c srb_append.c stream_test.c     \
          set_extent.c getname.c file_handle.c ntypes.c dangle.c error_test.c \
-         err_compat.c dtransform.c
+         err_compat.c dtransform.c filename.c
 
 TEST_OBJ=$(TEST_SRC:.c=.lo)
 
@@ -238,4 +238,7 @@ err_compat: err_compat.lo
 dtransform: dtransform.lo
 	@$(LT_LINK_EXE) $(CFLAGS) -o $@ dtransform.lo $(LIB) $(LIBHDF5) $(LDFLAGS) $(LIBS)
 
+filename: filename.lo
+	@$(LT_LINK_EXE) $(CFLAGS) -o $@ filename.lo $(LIB) $(LIBHDF5) $(LDFLAGS) $(LIBS)
+
 @CONCLUDE@
diff --git a/test/filename.c b/test/filename.c
new file mode 100644
index 0000000..992ae0d
--- /dev/null
+++ b/test/filename.c
@@ -0,0 +1,157 @@
+/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
+ * Copyright by the Board of Trustees of the University of Illinois.         *
+ * All rights reserved.                                                      *
+ *                                                                           *
+ * This file is part of HDF5.  The full HDF5 copyright notice, including     *
+ * terms governing use, modification, and redistribution, is contained in    *
+ * the files COPYING and Copyright.html.  COPYING can be found at the root   *
+ * of the source code distribution tree; Copyright.html can be found at the  *
+ * root level of an installed copy of the electronic HDF5 document set and   *
+ * is linked from the top-level documents page.  It can also be found at     *
+ * http://hdf.ncsa.uiuc.edu/HDF5/doc/Copyright.html.  If you do not have     *
+ * access to either file, you may request a copy from hdfhelp@ncsa.uiuc.edu. *
+ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
+
+/*
+ * Programmer:  Raymond Lu <slu@ncsa.uiuc.edu>
+ *              June 29, 2004
+ *
+ * Purpose:     Tests the "H5Fget_name" functionality
+ */
+
+#include "hdf5.h"
+#include "h5test.h"
+#include "testhdf5.h"
+
+#define FILENAME "get_file_name"
+#define GROUPNAME "group"
+#define DSETNAME "dataset"
+#define ATTRNAME "attribute"
+#define DTYPENAME "compound"
+#define NAME_BUF_SIZE   64
+
+#define RANK 2
+#define NX 4
+#define NY 5
+
+/* Compound datatype */
+typedef struct s1_t {
+    unsigned int a;
+    float        b;
+} s1_t;
+
+/* Used to make certain a return name _is_ the file name */
+#define VERIFY_NAME(x, val, where) do {					      \
+    if (GetTestVerbosity()>=VERBO_HI) {				              \
+	print_func("   Call to routine: %15s at line %4d in %s had value "    \
+		   "%ld \n", (where), (int)__LINE__, __FILE__, (long)(x));    \
+    }									      \
+    if (strcmp(x, val)) {					              \
+	TestErrPrintf("*** UNEXPECTED VALUE from %s should be %s, but is %s at line %4d " \
+		   "in %s\n", where, val, x, (int)__LINE__, __FILE__);        \
+	H5Eprint (H5E_DEFAULT, stdout);					      \
+    }									      \
+    strcmp(x, "");                                                            \
+} while(0)
+
+int main( void )
+{
+    char    filename[NAME_BUF_SIZE];
+    hid_t   fapl;
+    hid_t   file_id;
+    hid_t   group_id;
+    hid_t   dataset_id;
+    hid_t   space_id;  
+    hid_t   type_id;
+    hid_t   attr_id;
+    hsize_t dims[RANK] = {NX, NY};
+    char    name[NAME_BUF_SIZE];
+    ssize_t name_len;
+    herr_t  ret;
+
+    TESTING("H5Fget_name");
+         
+    /* Reset the library and get the file access property list */
+    h5_reset();
+    fapl = h5_fileaccess();
+
+    /* Initialize the file names */
+    h5_fixname(FILENAME, fapl, filename, sizeof filename);
+     
+    /* Create a new file_id using default properties. */
+    file_id = H5Fcreate(filename, H5F_ACC_TRUNC, H5P_DEFAULT, fapl );
+    CHECK(file_id, FAIL, "H5Fcreate"); 
+
+    /* Get and verify file name */
+    name_len = H5Fget_name(file_id, name, NAME_BUF_SIZE);
+    CHECK(name_len, FAIL, "H5Fget_name");
+    VERIFY_NAME(name, filename, "H5Fget_name");
+
+    /* Create a group in the root group */
+    group_id = H5Gcreate(file_id, GROUPNAME, 0);
+    CHECK(group_id, FAIL, "H5Gcreate"); 
+
+    /* Get and verify file name */
+    name_len = H5Fget_name(group_id, name, NAME_BUF_SIZE);
+    CHECK(name_len, FAIL, "H5Fget_name");
+    VERIFY_NAME(name, filename, "H5Fget_name");
+
+    /* Create the data space  */
+    space_id = H5Screate_simple(RANK, dims, NULL);
+    CHECK(space_id, FAIL, "H5Screate_simple"); 
+
+    /* Try get file name from data space.  Supposed to fail because 
+     * it's illegal operation. */
+    H5E_BEGIN_TRY {
+        name_len = H5Fget_name(space_id, name, NAME_BUF_SIZE);
+    } H5E_END_TRY;
+    VERIFY(name_len, FAIL, "H5Fget_name");
+
+    /* Create a new dataset */
+    dataset_id = H5Dcreate(file_id, DSETNAME, H5T_NATIVE_INT, space_id, H5P_DEFAULT);
+    CHECK(dataset_id, FAIL, "H5Dcreate"); 
+
+    /* Get and verify file name */
+    name_len = H5Fget_name(dataset_id, name, NAME_BUF_SIZE);
+    CHECK(name_len, FAIL, "H5Fget_name");
+    VERIFY_NAME(name, filename, "H5Fget_name");
+
+    /* Create an attribute for the dataset */
+    attr_id = H5Acreate(dataset_id,ATTRNAME,H5T_NATIVE_INT,space_id,H5P_DEFAULT);
+    CHECK(attr_id, FAIL, "H5Acreate");
+
+    /* Get and verify file name */
+    name_len = H5Fget_name(attr_id, name, NAME_BUF_SIZE);
+    CHECK(name_len, FAIL, "H5Fget_name");
+    VERIFY_NAME(name, filename, "H5Fget_name");
+
+    /* Create a compound datatype */
+    type_id = H5Tcreate(H5T_COMPOUND, sizeof(s1_t));
+    CHECK(type_id, FAIL, "H5Tcreate"); 
+
+    /* Insert fields */
+    ret = H5Tinsert (type_id, "a", HOFFSET(s1_t,a), H5T_NATIVE_INT);
+    CHECK(ret, FAIL, "H5Tinsert"); 
+
+    ret = H5Tinsert (type_id, "b", HOFFSET(s1_t,b), H5T_NATIVE_FLOAT);
+    CHECK(ret, FAIL, "H5Tinsert"); 
+  
+    /* Save it on file */
+    ret = H5Tcommit(file_id, DTYPENAME, type_id);
+    CHECK(ret, FAIL, "H5Tcommit"); 
+
+    /* Get and verify file name */
+    name_len = H5Fget_name(type_id, name, NAME_BUF_SIZE);
+    CHECK(name_len, FAIL, "H5Fget_name");
+    VERIFY_NAME(name, filename, "H5Fget_name");
+
+    H5Tclose(type_id);
+    H5Aclose(attr_id);
+    H5Dclose(dataset_id);
+    H5Sclose(space_id);
+    H5Gclose(group_id);
+    H5Fclose(file_id);
+
+    PASSED();
+    return 0;
+}