NetcdfDataset Class Reference
The top-level object that manages its member objects and the underlying netCDF data. More...
#import <NetcdfDataset.h>
Public Member Functions | |
| (BOOL) | - isValid |
| Returns YES if initialization was successful. | |
| (int) | - ncErrNo |
| Returns status of last netCDF library call. | |
| (NSString *) | - path |
| Returns path to current netCDF data file. | |
| (NetcdfDimension *) | - unlimitedDimension |
| Returns the unlimited dimension if it exists, else nil. | |
| (BOOL) | - ncSync |
| netCDF library wrapper to synchronize data in buffers with the disk file. | |
| (BOOL) | - reinitialize |
| Re-initializes ivars from current netCDF dataset; do this after ncSync. | |
| (NSString *) | - version |
| Returns netCDF library version string. | |
| (NSString *) | - errorMessageNumber: |
| Convert error code into localized error message. | |
| (NSError *) | - lastError |
| Returns an NSerror based on ncErrNo. | |
| (int) | - formatVersion |
| NetCDF file format version. 0 = error; 1 = netCDF classic; 2 = 64-bit large file. | |
| (NSMutableDictionary *) | - schema |
| The data structure without any data. | |
| (NetcdfStepPathLock *) | - pathLock |
| Returns the lock associated with a NetcdfDataset instance. | |
Initializers | |
| (id) | - init |
| Just a stub. | |
| (id) | - initFromFile:share:error: |
| Initializes with read-only access from an existing netCDF data file. | |
Data Access | |
These methods provide access to the data objects. | |
| (NSArray *) | - dimensions |
| Returns the array of NetcdfDimension objects. | |
| (NSArray *) | - variables |
| Returns the array of NetcdfVariable objects. | |
| (NSArray *) | - attributes |
| Returns the array of NetcdfAttribute objects; may be empty. | |
| (NetcdfDimension *) | - dimensionByName: |
| Returns a reference to a dimension given its name. | |
| (NetcdfVariable *) | - variableByName: |
| Returns a reference to a variable given its name. | |
| (NetcdfAttribute *) | - attributeByName: |
| Returns a reference to an attribute given its name. | |
Conventions | |
There are three global attributes defined by convention in the netCDF standard. They are optional, but netCDF compliant applications will recognize and use them. | |
| (NSString *) | - title |
| The optional global attribute "title" is defined by convention in netCDF; returns nil if not defined. | |
| (NSString *) | - history |
| The optional global attribute "history" is defined by convention in netCDF; returns nil if not defined. | |
| (NSString *) | - conventions |
| The optional global attribute "Conventions" is defined by convention in netCDF; returns nil if not defined. | |
Static Public Member Functions | |
| (NSError *) | + errorWithErrorNumber:info: |
| Returns an autoreleased NSError with the error code, domain and localized error message set. | |
Class Methods | |
| (id) | + datasetFromFile:share:error: |
| Convenience constructor. | |
Protected Attributes | |
| NSString * | path |
| path to the netCDF data file | |
| int | countDimensions |
| number of dimensions | |
| int | unlimitedDimid |
| index of unlimited dimension or -1 if no unlimited dimension | |
| NSMutableArray * | dimensions |
| array of NetcdfDimension | |
| int | countVariables |
| number of variables | |
| NSMutableArray * | variables |
| array of NetcdfVariable | |
| int | countAttributes |
| number of global attributes | |
| NSMutableArray * | attributes |
| array of NetcdfAttribute (global attributes) | |
| BOOL | isValid |
| set to NO if there was an error initializing or opening | |
| int | ncErrNo |
| return value for last netcdf library calls | |
| NetcdfStepPathLock * | pathLock |
| local cache of the shared lock | |
Detailed Description
The top-level object that manages its member objects and the underlying netCDF data.The NetcdfDataset object contains arrays of global attributes, dimensions and variables which it owns and manages. The public interfaces refer to them only by name. NetCDF id numbers are only for internal use.
This is a read-only class, and must be initialized from an existing netCDF dataset file. A NetcdfDataset object does not contain the actual data; rather it is an object-oriented interface to an underlying netCDF dataset. The file remains open for as long as the NetcdfDataset object exists; the file is closed only upon deallocation.
The netCDF standard defines three global attributes by convention. Pre-built methods are provided to access them if those attributes are available. NetCDF-compliant applications should recognize and use them.
Methods for creating, modifying and writing data to a netCDF dataset are provided in NetcdfMutableDataset.
Member Function Documentation
| - (NetcdfAttribute *) attributeByName: | (NSString *) | name |
Returns a reference to an attribute given its name.
The method recognizes two formats for the name
"variableName:attributeName" returns a variable attribute
"attributeName" returns a global attribute
Returns nil if not found. ncErrNo set on failure of netCDF library call.
| - (NSString *) conventions |
The optional global attribute "Conventions" is defined by convention in netCDF; returns nil if not defined.
A path string pointing to a directory that contains documentation for the user-defined conventions used in the dataset. See the netCDF documents for details.
| + (id) datasetFromFile: | (NSString *) | path | ||
| share: | (BOOL) | share | ||
| error: | (NSError **) | errorP | ||
Convenience constructor.
Opens an existing netCDF data file for read-only access. Creates and initializes any needed dimensions, attributes and variables.
If share == YES, it tells the netCDF library that the underlying data may be writable by another object, and to use a cautious cache policy. Also asks for a pathLock, and uses it during initialization. It unlocks after initialization.
On error, returns nil and an NSError object with the netCDF error code. The argument to error: holds a pointer where a returned NSError object (if any) will be stored. This pointer may be NULL, in which case no error information will be returned.
Returns an autoreleased object pointer.
| - (NetcdfDimension *) dimensionByName: | (NSString *) | name |
Returns a reference to a dimension given its name.
Returns nil if not found. ncErrNo set on failure of netCDF library call.
| - (NSString *) errorMessageNumber: | (int) | errNo |
Convert error code into localized error message.
In addition the the error codes and messages defined by netCDF, NetcdfStep defines the following codes and messages:
NCS_STRINGSIZE_E -128: NSString longer than dimension of offset for writing
NCS_DATASIZE_E -129: NSData is too small for reading or writing
NCS_ARRAYSIZE_E -130: NSArray has fewer memvers than dimension or offset for writing
NCS_STRINGENCODING_E -131: NSString Unicode can't be converted to C string with default encoding
Returns a localized error message.
| + (NSError *) errorWithErrorNumber: | (int) | errNo | ||
| info: | (NSDictionary *) | info | ||
Returns an autoreleased NSError with the error code, domain and localized error message set.
The implementation of this method has been moved to NetcdfStepError, but a wrapper is kept here for compatibility. New programming should use [NetcdfStepError +errorWithErrorNumber:info:]
| - (NSString *) history |
The optional global attribute "history" is defined by convention in netCDF; returns nil if not defined.
As a matter of good programming practice, you should use this to track changes to the data.
| - (id) init |
Just a stub.
Use -initFromFile:share:error:
Sets isValid = NO.
| - (id) initFromFile: | (NSString *) | path | ||
| share: | (BOOL) | share | ||
| error: | (NSError **) | errorP | ||
Initializes with read-only access from an existing netCDF data file.
Creates and initializes any needed dimensions, attributes and variables.
If share == YES, it tells the netCDF library that the underlying data ay be writable by another object, and to use a cautious cache policy. Also requests a pathLock, and uses it while initializing; unlocks after initialization.
On error, returns nil and an NSError object with the netCDF error code. The argument to error: holds a pointer where a returned NSError object (if any) will be stored. This pointer may be NULL, in which case no error information will be returned.
Returns the initialized object.
| - (NSError *) lastError |
Returns an NSerror based on ncErrNo.
Sets the error code to ncErrNo, the domain to "netCDF" and its userInfo dictionary will contain:
key: NSLocalizedDescription value: NSString human readable error message
key: "path" value: NSString path to the netCDF data file
key: "class" value: NSString "NetcdfDataset"
| - (NetcdfStepPathLock *) pathLock |
Returns the lock associated with a NetcdfDataset instance.
Returns a NetcdfStepPathLock, a subclass of NSLock. If the dataset is opened with share == NO, returns nil.
For performance, this is implemented as a local reference to the pathLock, and is the preferred means of accessing it.
| - (BOOL) reinitialize |
Re-initializes ivars from current netCDF dataset; do this after ncSync.
Currently, this implementation releases the dimensions, attributes and variables, and re-instantiates them with new values from the netCDF dataset.
| - (NSMutableDictionary *) schema |
The data structure without any data.
Mutable datasets can use a schema to create or modify a dataset structure.
key: "path" value: path to netCDF data file.
key: "format" value: NSNumber of file format version
key: "dimensions" value: NSArray of dimension schema.
key: "attributes" value: NSArray of attribute schema, possibly empty.
key: "variables" value: NSArray of variable schema.
| - (NSString *) title |
The optional global attribute "title" is defined by convention in netCDF; returns nil if not defined.
A netCDF-compliant application will recognize this as the standard place for a title string.
| - (NetcdfVariable *) variableByName: | (NSString *) | name |
Returns a reference to a variable given its name.
Returns nil if not found. ncErrNo set on failure of netCDF library call.
