From 8ef6fcba4c70c0d945c7148ac17b9822f6b3177f Mon Sep 17 00:00:00 2001 From: Frank Baker Date: Thu, 2 Sep 2004 18:00:33 -0500 Subject: [svn-r9192] Purpose: Add H5Zget_filter_info and h5zget_filter_info_f. Other minor edits. Platforms tested: Mozilla --- doc/html/RM_H5Z.html | 144 ++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 132 insertions(+), 12 deletions(-) diff --git a/doc/html/RM_H5Z.html b/doc/html/RM_H5Z.html index 4b08e69..b673ebf 100644 --- a/doc/html/RM_H5Z.html +++ b/doc/html/RM_H5Z.html @@ -72,15 +72,16 @@ These functions enable the user to configure new filters for the local environment. - + for a list of identifiers for standard filters + distributed with the HDF5 Library.
+
-       +       -       +       @@ -95,16 +96,16 @@ as the corresponding C function.
- + for a list of valid filter identifiers.
+
-       +       -       +       @@ -179,7 +180,7 @@ data compression. H5Z_filter_t filter     IN: Filter identifier. See the introduction to this section of the reference manual - for a list of valid filter identifiers
Returns:
Returns a non-negative value if successful; @@ -210,6 +211,124 @@ END SUBROUTINE h5zfilter_avail_f --> + + + +
+
+
Name: H5Zget_filter_info +
Signature: +
herr_t + H5Zget_filter_info( + H5Z_filter_t filter, + unsigned int *filter_config_flags + ) +
Purpose: +
Retrieves information about a filter. +
Description: +
+ H5Zget_filter_info retrieves information about a filter. + At present, this means that the function retrieves a + filter's configuration flags, indicating whether the filter is + configured to decode data, to encode data, neither, or both. +

+ If filter_config_flags is not set to NULL + prior to the function call, the returned parameter contains a + bit field specifying the available filter configuration. + The configuration flag values can then be determined through + a series of bitwise AND operations, as described below. +

+ Valid filter configuration flags include the following: + + + + + + + + + +
    H5Z_FILTER_CONFIG_ENCODE_ENABLEDEncoding is enabled for this filter +
 H5Z_FILTER_CONFIG_DECODE_ENABLED    Decoding is enabled for this filter +
 (These flags + are defined in the HDF5 Library source code file + H5Zpublic.h.) +
+ A bitwise AND of the returned + filter_config_flags and a valid + filter configuration flag will reveal whether + the related configuration option is available. + For example, if the value of +
+      + H5Z_FILTER_CONFIG_ENCODE_ENABLED + & + filter_config_flags +
+ is true, i.e., greater than 0 (zero), + the queried filter is configured to encode data; + if the value is FALSE, + i.e., equal to 0 (zero), + the filter is not so configured. +

+ If a filter is not encode-enabled, the corresponding + H5Pset_* function will return an error if the + filter is added to a dataset creation property list (which is + required if the filter is to be used to encode that dataset). + For example, if the H5Z_FILTER_CONFIG_ENCODE_ENABLED + flag is not returned for the SZIP filter, + H5Z_FILTER_SZIP, a call to H5Pset_szip + will fail. +

+ If a filter is not decode-enabled, the application will not be + able to read an existing file encoded with that filter. +

+ This function should be called, and the returned + filter_config_flags analyzed, before calling + any other function, such as H5Pset_szip, + that might require a particular filter configuration. + +

Parameters: +
+
H5Z_filter_t filter +
IN: Identifier of the filter to query. + See the introduction to this section of the reference manual + for a list of valid filter identifiers. +
unsigned int *filter_config_flags +
OUT: A bit field encoding the returned filter information +
+
Returns: +
Returns a non-negative value on success, + a negative value on failure. + +
Fortran90 Interface: +
+ 
+SUBROUTINE h5zget_filter_info_f(filter, config_flags, hdferr)
+
+  IMPLICIT NONE
+  INTEGER, INTENT(IN)  :: filter        ! Filter, may be one of the
+                                        ! following:
+                                        !     H5Z_FILTER_DEFLATE_F
+                                        !     H5Z_FILTER_SHUFFLE_F
+                                        !     H5Z_FILTER_FLETCHER32_F
+                                        !     H5Z_FILTER_SZIP_F
+  INTEGER, INTENT(OUT) :: config_flags  ! Bit field indicating whether
+                                        ! a filter's encoder and/or
+                                        ! decoder are available
+  INTEGER, INTENT(OUT) :: hdferr        ! Error code
+
+END SUBROUTINE h5zfilter_avail_f
+
+ +
+ +
@@ -446,7 +565,8 @@ END SUBROUTINE h5zfilter_avail_f
H5Z_filter_t filter     IN: Identifier of the filter to be unregistered. See the introduction to this section of the reference manual - for a list of valid filter identifiers
Returns:
Returns a non-negative value if successful; @@ -515,7 +635,7 @@ And in this document, the Describes HDF5 Release 1.7, the unreleased development branch; working toward HDF5 Release 1.8.0 -- cgit v0.12