Releases for netCDF utilities

QLA_netCDF4_library:

• Added features:

1. Implemented the option of using compact storage when defining a variable (QLA_def_var). 
2. Added storage=-1 option to QLA_def_var which will apply the most efficient storage method automatically depending on the dataset size.     

• Bug fixes:

1. Fixed an erroneous information message when creating a char dataset by commuting another datatype that stated that a dimension had to be created when one was already specified.
2. Fixed a bug in QLA_def_var when attempting to create a scalar string variable in netCDF-4 classic model files.

Included files:

1. QLA_netCDF4_sample.ipf
2. QLA_netCDF4_library.ipf
3. QLA_netCDF4_library_help.ihf
4. QLA_netCDF_reader.ipf
5. QLA_netCDF_reader_help.ihf
6. string2text2char2byte.ipf 
7. GNU_GENERAL_PUBLIC_LICENSE_version_2.ifn

QLA_netCDF4_library:

• Added features:

1. QLA_def_var will now create any type of scalar netCDF variable if passed a wave with precisely 1 element and no dimensions are listed. Previously only scalar variables of 'double' type were available.

Included files:

1. QLA_netCDF4_sample.ipf
2. QLA_netCDF4_library.ipf
3. QLA_netCDF4_library_help.ihf
4. QLA_netCDF_reader.ipf
5. QLA_netCDF_reader_help.ihf
6. string2text2char2byte.ipf 
7. GNU_GENERAL_PUBLIC_LICENSE_version_2.ifn

QLA_netCDF4_library:

• Changed behaviour:

1. To ensure compatibility with future versions of Igor Pro the library constant 'QLA_version' was removed and replaced with a function of the same name see: QLA_version.

• Other:

1. Some mistakes in error messages rectified.
2. Some boilerplating in error handling to avoid mistakes.

QLA_netCDF_reader:

• Added features:

1. The type of file being loaded can now distinquish between netCDF-3 classic format and 64-bit offset format and will be correctly indicated in the file attributes information. 
2. A more helpful error message is now printed to the history area when attempting to load a CDF-5 (64-bit data format) file which isn't supported. 
3. If an non-critical error occurs during file loading a warning will be printed in the history area. 
4. QLA_get_att now accepts a list of possible attributes returning the first found. Useful in situations where there maybe be multiple possible attributes with the same meaning e.g. _FillValue & missing_value.
5. Added QLA_dump function as a menu option to display the entire netCDF header information in a notebook window. Analogous to the command line call ncdump -h filename.nc.
6. Added QLA_kind function to return the type of netCDF file as a string. Analogous to the command line call ncdump -k filename.nc.
7. QLA_netCDF has an added optional dump parameter which when set will call QLA_dump displaying the CDL formatted netCDF header information when a file is successfully loaded.

• Bug fixes:

1. Fixed a bug in how NaN or Inf values in attributes were drawn. 

• Other:

1.  Functions completely rewritten and factored to improve readability and increase efficiency. Some performance enhancements gained as a result.
2. An empty data folder is not longer left orphanned if loading the file fails for any reason.

Included files:

1. QLA_netCDF4_sample.ipf
2. QLA_netCDF4_library.ipf
3. QLA_netCDF4_library_help.ihf
4. QLA_netCDF_reader.ipf
5. QLA_netCDF_reader_help.ihf
6. string2text2char2byte.ipf 
7. GNU_GENERAL_PUBLIC_LICENSE_version_2.ifn

QLA_netCDF4_library:

• Bug fixes:

1. Fixed the misuse of the version #pragma.

QLA_netCDF_reader:

• Bug fixes:

1. Fixed a bug in the representation of floating point attributes that were also arrays e.g. valid_range whereby the precision (number of decimals) would be overstated for elements after 0 in the array.
2. Fixed a bug when loading netCDF-3 files when using the transform option which cold result in the data not being transformed, or more correctly the data being transformed multiple times and possible ending up back at the start. The side effect being that loading netCDF-3 files is also improved. 

• Other:

1. QLA_netCDF function restructured for better readability.

Included files:

1. QLA_netCDF4_sample.ipf
2. QLA_netCDF4_library.ipf
3. QLA_netCDF4_library_help.ihf
4. QLA_netCDF_reader.ipf
5. QLA_netCDF_reader_help.ihf
6. string2text2char2byte.ipf 
7. GNU_GENERAL_PUBLIC_LICENSE_version_2.ifn

QLA_netCDF4_library:

• Added features:

1. Added CFCheck library constant to control the Climate and Forecast conventions compliance checking of dimension, varliable, group, and attribute names; with CFCheck=1 set these names are tested whether they comply with the CF standard. That is, names should begin with an ASCII letter and contain only ASCII letters, numbers, and the underscore character (U+005F). A warning will be given, if the error handler is set >0, if a name contains other characters, spaces, or begins with an underscore and is not a reserved netCDF name. Setting CFCheck=0 dissables any checking of names, though some may still raise errors if they are not also netCDF or HDF5 compliant. This allows non-CF compliant netCDFs to be created which may be appropriate when not working in Latin script.

• Changed behaviour:

1. The checking of variable names for Climate and Forecast conventions compliance has been altered so that names begining with an underscore now raise a warning.

• Other:

1. The version of the GNU General Public License under which this code is distributed was changed from 3 to 2 at the author's discretion (<https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt&gt;).

QLA_netCDF_reader:

• Other:

1. The version of the GNU General Public License under which this code is distributed was changed from 3 to 2 at the author's discretion (<https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt&gt;).

Included files:

1. QLA_netCDF4_sample.ipf
2. QLA_netCDF4_library.ipf
3. QLA_netCDF4_library_help.ihf
4. QLA_netCDF_reader.ipf
5. QLA_netCDF_reader_help.ihf
6. string2text2char2byte.ipf 
7. GNU_GENERAL_PUBLIC_LICENSE_version_2.ifn

QLA_netCDF4_library:

• Added features:

1. Added the UTF8CharSet library constant to control the text encoding of string attributes. With UTF8CharSet=1 set the full UTF8 character set will be used; with UTF8CharSet=0 set then any strings will be stripped of characters that are not pure ASCII. Regardless the attributes are marked as ASCII when written by convention.

QLA_netCDF_reader:

• Bug fixes:

1. Fixed where CHAR type datsets would be miss-identified as STRING if the number of printable characters wasn't uniform accross the entire array. 

• Other:

1. Added check for illegal single and double quotes, as well as (semi-)colons in dimension labels.

Included files:

1. QLA_netCDF4_sample.ipf
2. QLA_netCDF4_library.ipf
3. QLA_netCDF4_library_help.ihf
4. QLA_netCDF_reader.ipf
5. QLA_netCDF_reader_help.ihf
6. string2text2char2byte.ipf 

QLA_netCDF4_library:

• Added features:

1. It is no longer necessary to define a group using QLA_def_grp before creating datasets or attributes of that group. If a none-existant group is referenced by any of QLA_def_dim_var, QLA_def_unlim_dim_var, QLA_def_dim, QLA_def_unlim_dim, QLA_def_var, QLA_put_glob_att, QLA_put_glob_att_text, QLA_put_glob_att_list, QLA_put_glob_att_wave then the group will be created automatically. 

• Changed behaviour:

1. QLA_def_dim and QLA_def_unlim_dim by default no longer write any data to file irrespective of what is passed to them. As a result delfate and shuffle also have no effect. This behaviour is controlled by the writeDim library constant, to restore writing of data fo file set writeDim=1.    

• Performance enhancements:

1. The time required to determine whether a string variable is really char has been reduced.

QLA_netCDF_reader:

• Added features:

1. Added illegalPreStr and illegalSuffStr strings which should be prepended or appended to any netCDF variable which has a name that conflics with any function or operation. One or both of either illegalPreStr or illegalSuffStr can be defined, or if both are zero length strings ("") then the default behaviour of appending a number to the variable name is restored.

• Performance enhancements:

1. The time required to unpack a variable has been reduced by ~⅓ through the use of multithreading.
2. The time required to determine whether a string variable is really char has been reduced.

• Other:

1. The documentation for the unpack option was fixed to reflect that unpack=0 not only range checks and scales data where appropriate, but also sets the fill value to NaN in floating point variables (float/real & double).

Included files:

1. QLA_netCDF4_sample.ipf
2. QLA_netCDF4_library.ipf
3. QLA_netCDF4_library_help.ihf
4. QLA_netCDF_reader.ipf
5. QLA_netCDF_reader_help.ihf
6. string2text2char2byte.ipf 

QLA_netCDF4_library:

• Added features:

1. QLA_def_var will now create a scalar netCDF variable if passed a wave with precisely 1 element and no dimensions are listed. Currently only scalar variables of 'double' type are available.

• Bug fixes:

1. Fixed where byte data was converted to char when written to netCDF-4 classic files.

Added project updater headers.

Included files:

1. QLA_netCDF4_sample.ipf
2. QLA_netCDF4_library.ipf
3. QLA_netCDF4_library_help.ihf
4. QLA_netCDF_reader.ipf
5. QLA_netCDF_reader_help.ihf
6. string2text2char2byte.ipf 

QLA_netCDF4_library:

• Added features:

1. Support for creating fixed width char datasets added.
2. QLA_def_var, QLA_def_dim_var and QLA_def_unlim_dim_var now create char type datasets if 1 is passed for the type parameter. The input wave can be a 1-D text wave of variable width (string) or 2-D text wave of fixed width (char), as well as a 1- or 2-D byte wave. String, char, and byte datasets can be created from any combination of input. See Character data types for a full description of the library behaviour.

• Changed behaviour:

1.  All text attributes and char data are written as null-terminated fixed width ASCII encoded strings instead of null-padded UTF-8 strings.
2. QLA_def_dim and QLA_def_unlim_dim by default create 32-bit floating point dimensions unless explicitly specified by setting the type parameter. The validity of the dimension is no longer checked as values are not given any special significance in netCDF - an array of 0's is the default.  
3. QLA_def_dim_var, QLA_def_unlim_dim_var; it is no longer an error to define a string type dimension variable.
4. QLA_def_var, QLA_def_dim, QLA_def_unlim_dim, QLA_def_dim_var and QLA_def_unlim_dim_var; setting shuffle is now only valid when compression is also being used (deflate > 0) in functions that accept the shuffle parameter. 
5. QLA_def_var, QLA_def_dim, QLA_def_unlim_dim, QLA_def_dim_var and QLA_def_unlim_dim_var; Added a check for the maximum dimension size in classic model files which is 2³² − 1 points. Datasets will be truncated at that number and a warning given.
6. QLA_def_var now gives a specific error when attempting to define a scalar variable - that is a variable of  size 1 that has no dimensions - which is not currently supported.

QLA_netCDF_reader:

• Added features:

1. Added CharAsText symbol which affects how QLA_get_nc treats CHAR type data. With CharAsText defined arrays of CHAR data are converted to 1D text waves of variable length strings. The metadata is unchanged by this so previously CHAR datasets will remain described as such.

• Bug fixes:

1. Removed trailing space after netCDF-4 in the type attribute of file_attributes.
2. Fixed where not all dimensions would be listed for variables with a dimension of zero size. Note that the size of the dimension might be listed as 0 for the variable when the actual dimension has a greater size.
3. CHAR type dimensions in netCDF-4 now correctly list the second dimension in the metadata. Previously only the first dimension was represented.
4. The CDL syntax of scalar netCDF variables in now correct as the trailing '()' is removed.

Added string2text2char2byte.ipf containing functions to manipulate char, text, and byte data.

Included files:

1. QLA_netCDF4_sample.ipf
2. QLA_netCDF4_library.ipf
3. QLA_netCDF4_library_help.ihf
4. QLA_netCDF_reader.ipf
5. QLA_netCDF_reader_help.ihf
6. string2text2char2byte.ipf 

QLA_netCDF_reader:

• Bug fixes:

1. Fixed an issue where QLA_inq_att returned nothing for variables with only one attribute.
2. The CHAR data type is now handled correctly and described properly. Previously CHAR data was represented as byte in netCDF-3 and variable length string in netCDF-4. This fix didn't make it into 1.2.0.

Included files:

1. QLA_netCDF4_sample.ipf
2. QLA_netCDF4_library.ipf
3. QLA_netCDF4_library_help.ihf
4. QLA_netCDF_reader.ipf
5. QLA_netCDF_reader_help.ihf

QLA_netCDF4_library:

• Added features:

1.  QLA_def_var now handles rare cases where a variable is defined with the same name as a dimension. This is done by prepending _nc4_non_coord_ to the variable name and is hidden by the netCDF library when read.

• Bug fixes:

1. _Netcdf4Dimid now written in a scalar rather than simple dataspace.
2. A bug existed where an HDF5 library error would sometimes be returned stating something about invalid dimension sizes. This was an Igor bug originating from the initial values in a free wave being undefined and was fixed in build 37423.
3. Added a check to differentiate between string and char datasets when extending a dataset using QLA_def_var or QLA_extend.
4. Added checks for the validity of string (or char) type dimensions. Note: char isn't currently a supported datatype.

QLA_netCDF_reader:

• Added features:

1. Added the .hdf5 file extension to the list of file filters in the open file dialogue.

• Bug fixes:

1. Fixed a bug when attempting to open a CDF file (note: not netCDF) that occurs when attempting to determine the size and number of dimensions in the file. CDF (Common Data Format) files are not supported though netCDF-3 is based upon CDF. The problem exists because CDF files are technically the same as netCDF-3 files and have the .cdf file extension as do old netCDF-3 files - the recommended extension for netCDF was changed to .nc from .cdf in 1994 though .cdf is still supported and sometimes used. CDF files can be loaded into memory though the results are undefined.
2. The CHAR data type is now handled correctly and described properly. Previously CHAR data was represented as byte in netCDF-3 and variable length string in netCDF-4. 

Included files:

1. QLA_netCDF4_sample.ipf
2. QLA_netCDF4_library.ipf
3. QLA_netCDF4_library_help.ihf
4. QLA_netCDF_reader.ipf
5. QLA_netCDF_reader_help.ihf

QLA_netCDF4_library:

    Benchmarked against netCDF4.8.0-NC4-64.

• Added functions:

1.  QLA_def_unlim_dim_var replacing QLA_def_unlim_dim in creating unlimited dimension variables.
2.  QLA_extend adds a dedicated function for extending dimensions and variables.

• Changed behaviour:

1. QLA_def_unlim_dim creates an unlimited dimension rather than an unlimited dimension variable.
2. All QLA_def_functions now implement a default chunking strategy instead of writing datasets as a single chunk. 

• Added features:

1. All QLA_def_functions now accept an optional array of user defined chunksizes overriding the defaults        provided by the QLA netcDF-4 library. Library chunking defaults implemented.
2. QLA_def_unlim_dim, QLA_def_unlim_dim_var, QLA_def_var now can accept an optional extend parameter if    data is to be appended to an unlimited dimension. As such a dimension size miss-match is no longer a        critical error.
3. QLA_def_dim, QLA_def_dim_var, QLA_def_var now can accept the optional storage parameter to force        chunking in all cases or contiguous in certain cases.
4. An error handler for all functions implemented (see: Library error handling).
5. Help file (QLA_netcdf4_library_help.ihf) was added.

• Bug fixes:    

1. QLA_update_var now preserves the compression settings and layout of the variable being updated.

QLA_netCDF_reader:

     Benchmarked against netCDF4.8.0-NC4-64, Panoply 4, HDFView 3.1.2.

• Added features:

1. Help file (QLA_netcdf_reader_help.ihf) was added.
2. Added the obsolete .cdf file extension to the list of file filters in the open file dialogue.

• Bug fixes:    

1. Fixed erroneous version number #pragma.
2. Added missing DefaultTab #pragma.    
3. Fixed a bug that left a trailing semi-colon after defining unlimited dimension sizes in the dimension list of netCDF-3 files.
4. Fixed a bug that would leave a leading path string in the dimension list of a dimension of a netCDF-4.

• Known issues

1.  The representation of the mantissa of floating point (float or double) attributes can vary due to uncertainties         in floating point precision. This is most likely to occur with actual_min, actual_max, and actual_range         attributes where there may be a difference in the number of decimal places printed when compared to the         reference software (netCDF4.8.0-NC4-64).

Included files:

1. QLA_netCDF4_sample.ipf
2. QLA_netCDF4_library.ipf
3. QLA_netCDF4_library_help.ihf
4. QLA_netCDF_reader.ipf
5. QLA_netCDF_reader_help.ihf

Included files:

QLA_netCDF4_sample.ipf

QLA_netCDF4_library.ipf

QLA_netCDF_reader.ipf