NetcdfStep Release Notes (Mac OS X edition)
Version 1.0.5
Fixed various warnings reported by new LLVM/Clang compiler.
Fixed (or explained) various static analyzer warnings.
String encoding (introduced in 1.0.3) made -...AsString methods crash if garbage in the data makes a string un-encodable. Added a fallback to try C-string conversion, and if that fails return an error. (This is still not completely airtight, but eliminates a crash.) The error message now mentions string conversion of UTF8 to/from C-string.
Updated project file and tested with XCode 4.6.2 (Mountain Lion).
Version 1.0.4
Fixed deadlock in error handling if creating a new NetcdfDataset in share mode fails.
Renamed localization file.
Tested with XCode 4.3 (Lion).
iOS: An experimental port to iOS 5 exists, and works. It supports netcdf 3.6.2 which means local file access only; this is a serious limitation for a mobile device. Porting opendap or netcdf 4.x will be difficult because of missing libraries in iOS, and the limitations of mobile devices in general. While it is possible to port the missing libraries, this is not enough. Mobile devices are not scientific workstations: they lack large RAM space, lack virtual memory paging, and lack reliable high-speed network connections.
Version 1.0.3
Default installation is 32/64-bit universal.
Improvements to locking mechanism.
When deallocating a shared NetcdfDataset, it now locks the nc_close operation.
Advice on using locks for shared read-only situations has been changed to recommend using a lock.
Compatible with Xcode 4, but PPC architecture is no longer supported. Compatible with Xcode 3.2 if PPC architecture is needed.
Various cleanups for 64-bit compatibility.
Corrected a severe bug in NetcdfMutableDimension -createByOwner:fromSchema: that failed to initialize the length.
Replaced deprecated OS X Foundation methods in string handling with modern ones. These new methods require C string conversions to use a specified encoding/decoding. Therefore new NetcdfStep APIs were added to NetcdfVariable and NetcdfAttribute to set and get the encoding for string conversion; the default is NSUTF8StringEncoding.
Many improvements to the sample/test application NCStest.
Version 1.0.2 Minor bug fixes and testing for compatibility with Snow Leopard
New, optional build target for 32/64-bit Intel requires OS X 10.5 or higher
Some adjustments to the build parameters for compatibility with 10.6 & Xcode 3.1
Some methods failed to check for null pointers in the NSError** argument; a null pointer means that no error
information should be returned, not to crash the program.
Various cleanups of things found by Clang Static Analyzer
More small improvements to documentation
Version 1.0.1 Minor cleanups for documentation and build processes.
Removed an unnecessary dependency on Cocoa.framework
New build target to separately make HTML documentation. Installation is now optional.
New build target to install documentation in Xcode 3
Version 1.0.0 The API is declared complete and frozen. All obsolete interfaces have been removed.
API documentation is installable into Xcode 3.
Version 0.6.3 Fixes some bugs and adds a minor feature
A serious bug in -(BOOL) varGetData:asType: where if the type was NC_LONG it would attempt to write instead of read. Fixed
HTML documentation failed to correctly generate. Fixed
[NetcdfDataset attributeByName:] now recognizes either "attributeName" as a global attribute or "variableName:attributeName" as a variable attribute and returns the corresponding attribute reference.
Changed behavior of pathLock in [NetcdfMutableDataset createFile:overwrite:share:fillMode:formatVersion:error:]. In SHARE mode, it now remains locked until explicitly unlocked.
Version 0.6.2 Adds a minor feature and fixes several minor bugs
A new target was added that links against OPeNDAP libraries for remote or local access instead of netCDF. See http://www.opendap.org for more information. Unique to this target, one new method is introduced:
- (id) initFromURL:writable:share:error:
The sample application NCStest tests the remote access feature if it is enabled.
Library version numbers were not consistent across all build targets. Fixed.
An error when opening a file could release the pathLock twice. Fixed.
Make sure that the pathLock and the dataset path are always exactly the same.
Fixed compiler warnings about signed versus unsigned.
Revert the changes in 0.6.1 back to 32-bit unsigned int. I misunderstood the specs.
Apply patch from Unidata to netcdf-3.6.2/libsrc/var.c that fixes a crash in large files.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Version-0.6.1 Fixes some bugs.
The schema mechanism was saving/retrieving dimension lengths using 32-bit unsigned int; changed to 64-bit unsigned long long. This corrects direcly or indirectly:
- (NSMutableDictionary *) schema
- (NetcdfVariable *) createByOwner:fromSchema:
- (NetcdfDimension *) createByOwner:fromSchema:
- (NetcdfDimension *) addDimension:length:error:
- (NetcdfDimension *) addDimension:withSchema:error:
- (id) createByOwner:fromSchema:
-(NSArray *) shape and -(id)initByOwner:varid: were saving the dimension lengths as 32-bit unsigned int; changed to 64-bit unsigned long long; corrected documentation.
Minor coding style changes. Removed deprecated code that was not being used.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Version 0.6.0 Adds initial support for multithreaded applications
This version breaks compatibility with version 0.5.2 by renaming some methods and adding a new ivar.
Fixed major memory leak due to a circular retain.
New class NetcdfStepPathLock manages locks on the file path; see documentation.
Specifying share: YES when opening or creating a NetcdfDataset will automatically make a shared PathLock for the new instance, and wraps the initialization in [pathLock lock] and [pathLock unlock].
New method in NetcdfDataset to return the lock on the path. How this lock is used is at the discretion of the application programmer:
- (NetcdfStepPathLock *) pathLock
Made handling of file path arguments more robust.
- (NSString *) errorMessageNumber: has been reimplemented in NetcdfStepError. Now it returns a localized message and also recognizes the new error codes for NetcdfStep.
In NetcdfDataset, NetcdfDimension, NetcdfAttribute and NetcdfVariable, renamed a method to be more descriptive of its operation:
- (NSError *) lastError formerly - (NSError *) error
In NetcdfDataset and NetcdfMutableDataset, opening or creating a file now allows NULL as an argument for the error handler;
Better descriptions of the lastError methods in documentation.
Added a new build target to XCode project. NetcdfStep_fink uses an external netCDF installation in the fink system at /sw/lib/libnetcdf.dylib
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Version 0.5.2 Uses an installer package for the framework.
Fixed buffer overrun in ...PutStrings methods when input strings are longer than dimension or offset; generates an error.
...PutStrings methods will automatically pad short input strings with nulls to fit variable.
More checking for string conversion compatibility between Unicode and ASCII.
NCStest sample program now tests new string writing behavior.
New class NetcdfStepError generates custom NSError objects
+ (NSError *) errorWithErrorNumber:info:
- (NSError *) initWithErrorNumber:info:
New error codes specific to NetcdfStep; see documentation. Many methods have been updated to return new error codes instead of generic EINVAL.
New convenience methods for generating NSError information from NetcdfDataset, NetcdfDimension, NetcdfAttribute and NetcdfVariable:
- (NSError *) error
Corrected documentation of certain error code returns.
Many major and minor corrections to documentation.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Version 0.5.1 fixes many bugs
Fixed allocation of temporary buffers for ...PutStrings methods.
Should return NO for all error conditions in ...PutStrings methods.
Relaxed sanity checking for ...PutStrings methods.
Corrected sanity checking in -(BOOL)setIndexWithValues: and -(BOOL)setOffsetWithValues: and -(BOOL)setStrideWithValues:
Removed bad sanity checking in -(BOOL)setMapWithValues:
Corrected vague error codes in many places.
Should return NO for all error conditions in ...PutData:ofType: methods.
More useful error information in several methods.
Abort on the first error for -(id)createByOwner:fromSchema: so correct error code is reported.
Fixed wrong count calculations in -(size_t)countVars and -(size_t)countVarm.
Corrected buffer allocation in -(NSData*)varsAsType: and -(NSArray*)varsAsString and -(NSData*)varmAsType: and -(NSArray*)varmAsString that were causing crashes.
The NCStest sample program gets 5 new unit tests, better error handling, and general updates.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Version 0.5.0 has major changes to the API and is not backwards compatible with earlier versions.
New methods for improved error management and compliance with Objective-C coding and naming conventions:
- (NetcdfDimension *) addDimensionWithSchema:error:
- (NetcdfDimension *) addDimension:length:error:
- (NSString *) renameAs:error:
- (NetcdfAttribute *) addAttributeWithSchema:error:
- (NetcdfAttribute *) addAttribute:type:values:error:
- (BOOL) deleteAttribute:error:
- (NetcdfAttribute *) copyAttributeTo:error:
- (NetcdfVariable *) addVariableWithSchema:error:
+ (NSError *) errorWithErrorNumber:info:
- (void) setIndex:
- (void) setOffset:
- (void) setStride:
- (void) setMap:
New methods are provided to compute the count of a pending data transfer:
- (size_t) countVar
- (size_t) countVara
- (size_t) countVars
- (size_t) countVarm
The following methods have been removed since their function is superseded in the new API:
- (BOOL) addDimension:
- (BOOL) addDimension:length:
- (BOOL) addAttribute:
- (BOOL) addAttribute:type:values:
- (BOOL) addVariable:
- (BOOL) deleteAttribute:
- (BOOL) copyAttributeTo:
- (BOOL) renameAs:
- (id) initFromFile:
+ (id) datasetFromFile:
- (id) initSharedFromFile:
+ (id) datasetSharedFromFile:
- (id) createFile:overwrite:share:fillMode:
- (id) createFileFromSchema:overwrite:share:fillMode:
- (id) inifFromFile:writable:share:
- (BOOL) sync
In order to eliminate a buffer overrun vulnerability, the following methods have been redefined and are not compatible with earlier versions of the framework:
- (BOOL) varGetData:asType:
- (BOOL) varaGetData:asType:
- (BOOL) varsGetData:asType:
- (BOOL) varmGetData:asType:
The following methods have new names, and now better conform to
Objective-C naming conventions:
- (BOOL) setIndexWithValues: formerly setIndex:
- (BOOL) setOffsetWithValues: formerly setOffset:
- (BOOL) setStrideWithValues: formerly setStride:
- (BOOL) setMapWithValues: formerly setMap:
- (NSString *) conventions formerly Conventions
- (NSString *) cFormat formerly CFormat
Error handling and checking have been improved in several places.
NetcdfDataset, NetcdfDimension, NetcdfAttribute and NetcdfVariable now implement -description to return a descriptive NSString.
Numerous improvements to API documentation.
Fixed several instances of a bug in allocating buffers for sub-sampled data.
Fixed a bug in 64-bit compilation.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Version 0.4.1 adds support for large (>2GB) file formats in netCDF-3.6.2 and adds the following methods
- (int) formatVersion
- (int) setDefaultFormatVersion:
The following methods are added to improve compliance with Objectove-C coding conventions
+ (id) datasetFromFile:share:error:
- (id) initFromFile:share:error:
- (id) createFile:fromSchema:overwrite:share:fillMode:formatVersion:error:
- (id) createFile:overwrite:share:fillMode:formatVersion:error:
- (id) initFromFile:writable:share:error:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Version 0.4.0 is a universal binary format supporting ppc and i386 architectures. Also, the netCDF library is now built in the project. Compatible with OS X 10.2.8 or higher on PowerPC; or 10.4 on Intel.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Version 0.3.5 fixes:
a memory overrun in -putAttribute:
a memory leak in initialization of NetcdfDataset objects
all compiler warnings
broken logic in -copyAttributeTo:
and cleans up the headers a bit.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Version 0.3.4 fixes a problem with building under Mac OS X 10.4 (Tiger).
A small test project, NCStest is included as an example of how to use NetcdfStep. It expects NetcdfStep.framework to be installed in your Library.