#import <NetcdfMutableDataset.h>
Public Member Functions | |
Initializers | |
These methods initialize a newly allocated NetcdfDataset with full read/write/modify access. The two -createFile... methods are so named to emphasize that they create new netCDF data files on disk during the initialization process. The philosophy here is that the netCDF dataset is the first creation, and the NetcdfDataset is derived from it (in contrast to the approach used by the C++ wrapper for netCDF). | |
| (id) | - createFile:overwrite:share:fillMode:formatVersion:error: |
| Initializes a newly allocated NetcdfDataset by creating a new, empty netCDF dataset on disk. | |
| (id) | - createFile:fromSchema:overwrite:share:fillMode:formatVersion:error: |
| Initializes a newly allocated NetcdfDataset by creating a new netCDF dataset, using a schema to define the structure. | |
| (id) | - initFromFile:writable:share:error: |
| Initializes from an existing netCDF data file. | |
| (id) | - initFromURL:writable:share:error: |
| Initializes from an existing netCDF file. Optional remote access via DAP. | |
Dataset Construction | |
These methods are used to build or modify the structure of the dataset | |
| (void) | - setDefineMode: |
| Explicitly enter or leave Define Mode. | |
| (int) | - setDefaultFormatVersion: |
| Set default file format for creating new datasets. | |
| (NetcdfDimension *) | - addDimensionWithSchema:error: |
| Creates a new dimension in the netCDF dataset and adds a NetcdfDimension the the NetcdfDataset. | |
| (NetcdfDimension *) | - addDimension:length:error: |
| Creates a new dimension in the netCDF dataset and adds a NetcdfDimension to the NetcdfDataset. | |
| (int) | - ncSetFillMode: |
| sets new fill mode, either NC_FILL or NC_NOFILL and returns old mode. | |
| (NetcdfVariable *) | - addVariableWithSchema:error: |
| Creates a new variable in the netCDF dataset and adds a new NetcdfVariable object. | |
| (NetcdfAttribute *) | - addAttributeWithSchema:error: |
| Creates a new global attribute in the netCDF dataset and adds it to the NetcdfDataset object. | |
| (NetcdfAttribute *) | - addAttribute:type:values:error: |
| Creates a new global attribute in the netCDF dataset and adds a new attribute to the NetcdfDataset object. | |
| (BOOL) | - deleteAttribute:error: |
| Deletes an attribute from the NetcdfVariable object and the netCDF dataset. | |
A category on NetcdfDataset that adds methods for writing existing datasets and creating new ones. Once opened for writeable access, the data, dimensions, attributes and variables may be modified. The file remains open as long as the NetcdfDataset object exists; the file is closed upon deallocation.
There are two ways to create a new dataset. The preferred way is to first create a schema that defines the structure, then alloc a new NetcdfStep object, then use -createFile:fromSchema:overwrite:share:fillMode:formatVersion:error: to create the disk file and initialize the new object. The other way is to create an empty disk file with -createFile:overwrite:share:fillMode:formatVersion:error: then add the dimensions, variables and attributes using the provided methods.
| - (NetcdfAttribute *) addAttribute: | (NSString *) | attName | ||
| type: | (nc_type) | attType | ||
| values: | (id) | values | ||
| error: | (NSError **) | errorP | ||
Creates a new global attribute in the netCDF dataset and adds a new attribute to the NetcdfDataset object.
Values may be NSString, NSNumber, NSArray of NSNumber, or a compatible subclass. Type conversion and data size are automatically handled. Type conversions that result in data truncation will cause an error.
On failure, 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.
On success, returns a pointer to the newly created NetcdfAttribute, and nil for the error.
| - (NetcdfAttribute *) addAttributeWithSchema: | (NSDictionary *) | schema | ||
| error: | (NSError **) | errorP | ||
Creates a new global attribute in the netCDF dataset and adds it to the NetcdfDataset object.
The attribute is defined by the schema which is an NSDictionary with the following required keys:
key: "name" value: the name string (NSString)
key: "type" value: the nc_type (NSNumber)
key: "values" value: NSString, NSNumber, or NSArray of NSNumber or a compatible subclass Type conversion and data size are automatically handled. Type conversions that result in data truncation will cause an error.
On failure, 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.
On success, returns a pointer to the new attribute, and nil for the error.
| - (NetcdfDimension *) addDimension: | (NSString *) | name | ||
| length: | (size_t) | size | ||
| error: | (NSError **) | errorP | ||
Creates a new dimension in the netCDF dataset and adds a NetcdfDimension to the NetcdfDataset.
If length == NC_UNLIMITED, the new dimension will be unlimited.
On failure, 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.
On success, returns a pointer to the newly created NetcdfDimension and nil for the error.
| - (NetcdfDimension *) addDimensionWithSchema: | (NSDictionary *) | schema | ||
| error: | (NSError **) | errorP | ||
Creates a new dimension in the netCDF dataset and adds a NetcdfDimension the the NetcdfDataset.
The schema keys are:
key: "name" value: NSString of the dimension name
key: "length" value: NSNumber of the dimension length
If the numeric value for the length key is NC_UNLIMITED, the new dimension will be unlimited.
On failure, 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.
On success, returns a pointer to the new NetcdfDimension and nil for the error.
| - (NetcdfVariable *) addVariableWithSchema: | (NSDictionary *) | schema | ||
| error: | (NSError **) | errorP | ||
Creates a new variable in the netCDF dataset and adds a new NetcdfVariable object.
The schema contains:
key: "name" value: name string (NSString)
key: "type" value: nc_type data type (NSNumber)
key: "dimensions" value: array of dimension schema (NSArray)
key: "attributes" value: array of attribute schema (NSArray)
The "name" and "type" keys must be defined. If the "dimensions" key is undefined or the array is empty, the created variable will be scalar. If the "attributes" key is undefined or the array is empty, no attributes will be created.
On failure, 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.
On success, returns a pointer to the new NetcdfVariable, and nil for the error.
| - (id) createFile: | (NSString *) | newPath | ||
| fromSchema: | (NSDictionary *) | schema | ||
| overwrite: | (BOOL) | overwrite | ||
| share: | (BOOL) | share | ||
| fillMode: | (BOOL) | fillMode | ||
| formatVersion: | (FormatVersion) | formatVersion | ||
| error: | (NSError **) | errorP | ||
Initializes a newly allocated NetcdfDataset by creating a new netCDF dataset, using a schema to define the structure.
The newly created netCDF dataset is opened with read/write/modify access.
The schema is used to construct the new netCDF dataset. The NetcdfAttribute, NetcdfDimension and NetcdfVariable objects are instantiated, and if the underlying netCDF dataset elements are successfully created, their isValid ivars are set to YES. If all the components are successfully created, isValid if set to YES for the new NetcdfDataset. The schema is an NSDictionary with five optional entries:
key: "path" value: NSString of path to file to be created
key: "format" value: NSNumber of netCDF file format version
key: "dimensions" value: NSArray of dimension schema
key: "variables" value: NSArray of variable schema
key: "attributes: values: NSArray of attribute schema
An empty or nil schema will result in an empty dataset.
Passing an empty or nil string for the newPath argument will look for the "path" key in the schema. The overwrite flag determines whether an existing dataset will be overwritten by the new one. The fillMode flag determines whether the variables of the new dataset will be filled with invalid data (YES), or left uninitialized (NO). The formatVersion may be 1 for netCDF classic or 2 for 64-bit large files; passing 0 will use the format from the schema if it is specified or default to 1 if it is not.
If share == YES, it tells the netCDF library that the dataset may be read by another object and to use a cautious cache policy. Also requests a pathLock and uses it for initialization. The pathLock is automatically unlocked after a successful 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.
| - (id) createFile: | (NSString *) | newPath | ||
| overwrite: | (BOOL) | overwrite | ||
| share: | (BOOL) | share | ||
| fillMode: | (BOOL) | fillMode | ||
| formatVersion: | (FormatVersion) | formatVersion | ||
| error: | (NSError **) | errorP | ||
Initializes a newly allocated NetcdfDataset by creating a new, empty netCDF dataset on disk.
Creates an empty dataset with no dimensions, variables or attributes. The new dataset is opened with read/write/modify access and set to Define Mode.
The overwrite flag determines whether an existing dataset will be overwritten by the new blank one. The fillMode flag determines whether the variables of the new dataset will be filled with invalid data (YES), or left uninitialized (NO). The formatVersion may be 1 for netCDF classic or 2 for 64-bit large files.
If share == YES, it tells the netCDF library that the data may be read by another object and to use a cautious cache policy. Also requests a pathLock, and locks it while initializing. You must explicitly unlock it after defining the dataset's structure.
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.
| - (BOOL) deleteAttribute: | (NSString *) | attName | ||
| error: | (NSError **) | errorP | ||
Deletes an attribute from the NetcdfVariable object and the netCDF dataset.
On success, returns YES.
On failure, 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.
| - (id) initFromFile: | (NSString *) | newPath | ||
| writable: | (BOOL) | writable | ||
| share: | (BOOL) | share | ||
| error: | (NSError **) | errorP | ||
Initializes from an existing netCDF data file.
Instantiates and initializes any needed NetcdfDimension, NetcdfAttribute and NetcdfVariable objects. The writable flag determines whether access is read-only or read/write/modify.
If share == YES, it tells the netCDF library that the underlying data may be read by another object and to use a cautious cache policy. Also requests a pathLock and uses it for initialization. It unlocks after a successful 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.
| - (id) initFromURL: | (NSURL *) | anURL | ||
| writable: | (BOOL) | writeable | ||
| share: | (BOOL) | share | ||
| error: | (NSError **) | errorP | ||
Initializes from an existing netCDF file. Optional remote access via DAP.
Creates and initializes any needed dimensions, attributes and variables.
If anURL points to a remote DAP server, then an http connection is attempted and blocks until success, error or timeout. Remote access is always read only, and the writable flag is ignored. This feature requires the use of the OPeNDAP libraries in place of the netCDF library; see www.opendap.org for details. A special build target is availble with this feature.
If anURL is a file URL, then the path is extracted and a local file is opened. Local access may be read/write/modify.
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 requests a pathLock, and uses it whilie initializing; unlocks after successful 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.
| - (int) ncSetFillMode: | (int) | fillMode |
sets new fill mode, either NC_FILL or NC_NOFILL and returns old mode.
This may be used prior to -addVariable:
| - (int) setDefaultFormatVersion: | (FormatVersion) | format |
Set default file format for creating new datasets.
There are two format versions: 1 = netCDF classic; 2 = 64-bit large file Passing an invalid format defaults to classic and sets ncErrNo. Return value is the previous value of the format number.
| - (void) setDefineMode: | (BOOL) | defMode |
Explicitly enter or leave Define Mode.
This is useful in two situations. One is when a dataset is initialized with -createFile:overwrite:share:fillMode:formatVersion:error: because this method implicitly leaves the new dataset in Define Mode. After adding all the dimensions, attributes and variables, -setDefineMode: NO. The other situation is when you are doing multiple modifications to the dataset; to minimize the overhead, -setDefineMode: YES before the changes and -setDefineMode: NO after. Sets ncErrNo.
1.5.7.1