[svn-r29269] Purpose: Improve Packet Table library

Description:
    The Packet Table API used to have fixed-length and variable-length functions
    (i.e., H5PTcreate_fl and H5PTcreate_vl), but in 2006, the vlen functions
    were ifdef'ed out with VLPT_REMOVED, see HDFFV-442. The majority of this
    revision includes removing unused vlen stuff, adding various vlen tests,
    initial code cleanup, and first pass of commenting.
    Details:
      - Removed the VLPT_REMOVED ifdef, but keep H5PTis_varlen and the free
        function because they are useful or even needed, but the free
        function's name is changed to be more appropriate for both
        read/write buffers, i.e., H5PTfree_vlen_buff.

      - The new test file, test_packet_vlen.c, contains tests showing packet
        tables, containing various types of vlen data, can be created with
        the fixed-length function

      - Two accessor functions were added per HDFFV-8623/patch 003.
            /* Returns the ID of the dataset associated with the packet table */
            hid_t H5PTget_dataset(hid_t table_id);

            /* Returns the ID of the datatype the packet table uses */
            hid_t H5PTget_type(hid_t table_id);

      - Various cleanup: replacing 0/-1 with SUCCEED/FAIL and H5I_BADID with
        H5I_INVALID_HID, and removing many warnings.

Platforms tested:
    Linux/32 2.6 (jam)
    Linux/64 (platypus)
    Darwin (osx1010test)

1 files changed, 25 insertions, 43 deletions

diff --git a/hl/src/H5PTpublic.h b/hl/src/H5PTpublic.h
index f919010..420275a 100644
--- a/hl/src/H5PTpublic.h
+++ b/hl/src/H5PTpublic.h
@@ -22,74 +22,58 @@ extern "C" {
 #endif
 
 /*-------------------------------------------------------------------------
- *
  * Create/Open/Close functions
- *
  *-------------------------------------------------------------------------
  */
+/* NOTE: H5PTcreate is replacing H5PTcreate_fl for better name due to the
+   removal of H5PTcreate_vl.  H5PTcreate_fl may be retired in 1.8.19. */
+H5_HLDLL hid_t H5PTcreate(hid_t loc_id, const char *dset_name,
+			hid_t dtype_id, hsize_t chunk_size, hid_t plist_id);
 
-H5_HLDLL hid_t H5PTcreate_fl ( hid_t loc_id,
-                      const char *dset_name,
-                      hid_t dtype_id,
-                      hsize_t chunk_size,
-                      int compression );
+H5_HLDLL hid_t H5PTopen(hid_t loc_id, const char *dset_name);
 
-#ifdef VLPT_REMOVED
-H5_HLDLL hid_t H5PTcreate_vl ( hid_t loc_id,
-                      const char *dset_name,
-                      hsize_t chunk_size );
-#endif /* VLPT_REMOVED */
+H5_HLDLL herr_t H5PTclose(hid_t table_id);
 
-H5_HLDLL hid_t H5PTopen( hid_t loc_id,
-                const char *dset_name );
-
-H5_HLDLL herr_t  H5PTclose( hid_t table_id );
+/* This function may be removed from the packet table in release 1.8.19. */
+H5_HLDLL hid_t H5PTcreate_fl(hid_t loc_id, const char *dset_name,
+			hid_t dtype_id, hsize_t chunk_size, int compression);
 
 
 /*-------------------------------------------------------------------------
- *
  * Write functions
- *
  *-------------------------------------------------------------------------
  */
-
-H5_HLDLL herr_t  H5PTappend( hid_t table_id,
-                   size_t nrecords,
-                   const void * data );
+H5_HLDLL herr_t H5PTappend(hid_t table_id, size_t nrecords, const void *data);
 
 /*-------------------------------------------------------------------------
- *
  * Read functions
- *
  *-------------------------------------------------------------------------
  */
+H5_HLDLL herr_t H5PTget_next(hid_t table_id, size_t nrecords, void * data);
 
+H5_HLDLL herr_t H5PTread_packets(hid_t table_id, hsize_t start,
+			size_t nrecords, void *data);
 
-H5_HLDLL herr_t  H5PTget_next( hid_t table_id,
-                     size_t nrecords,
-                     void * data );
+/*-------------------------------------------------------------------------
+ * Inquiry functions
+ *-------------------------------------------------------------------------
+ */
+H5_HLDLL herr_t H5PTget_num_packets(hid_t table_id, hsize_t *nrecords);
 
-H5_HLDLL herr_t  H5PTread_packets( hid_t table_id,
-                         hsize_t start,
-                         size_t nrecords,
-                         void *data );
+H5_HLDLL herr_t H5PTis_valid(hid_t table_id);
+
+H5_HLDLL herr_t H5PTis_varlen(hid_t table_id);
 
 /*-------------------------------------------------------------------------
  *
- * Inquiry functions
+ * Accessor functions
  *
  *-------------------------------------------------------------------------
  */
 
+H5_HLDLL hid_t H5PTget_dataset(hid_t table_id);
 
-H5_HLDLL herr_t  H5PTget_num_packets( hid_t table_id,
-                            hsize_t *nrecords );
-
-H5_HLDLL herr_t  H5PTis_valid( hid_t table_id );
-
-#ifdef VLPT_REMOVED
-H5_HLDLL herr_t  H5PTis_varlen( hid_t table_id );
-#endif /* VLPT_REMOVED */
+H5_HLDLL hid_t H5PTget_type(hid_t table_id);
 
 /*-------------------------------------------------------------------------
  *
@@ -113,11 +97,9 @@ H5_HLDLL herr_t  H5PTget_index( hid_t table_id,
  *-------------------------------------------------------------------------
  */
 
-#ifdef VLPT_REMOVED
-H5_HLDLL herr_t  H5PTfree_vlen_readbuff( hid_t table_id,
+H5_HLDLL herr_t  H5PTfree_vlen_buff( hid_t table_id,
                                size_t bufflen,
                                void * buff );
-#endif /* VLPT_REMOVED */
 
 #ifdef __cplusplus
 }