NetCDF Operations

NC_OpenFile [/Z /I /PATH=pathName ] refNum [as fileNameStr ]

Opens the named NetCDF Classic or NetCDF 64-bit offset format file.

Parameters

If fileNameStr is omitted or is "", or if the /I flag is used, NC_OpenFile presents an Open File dialog from which you can choose the file to load.

If you use a full or partial path for fileNameStr, see Path Separators for details on forming the path.


refNum	is the name of a numeric variable to receive the file reference number.
	refNum is set by NC_OpenFile if it actually opens a file for reading.
fileNameStr	The targeted file is specified by a combination of the pathName parameter and the fileNameStr parameter.

Flags


/Z	Prevents aborting of procedure execution if an error occurs.
/I	A Open File dialog is displayed to choose the file.
/PATH = pathName	Specifies the folder to look in for the file. pathName is the name of an existing symbolic path.

Output Variables


S_fileName	S_fileName is set to the opened file name if V_flag returns 0.
S_path	S_path is set to the path of the opened file name if V_flag returns 0.
V_flag	V_flag is set to 0 if no error occurred, otherwise it returns an error code.

Thread Safety

NC_OpenFile is thread-safe if fileNameStr is a full native path to an existing file. In this case an optional given pathName is ignored and not resolved.

NC_OpenFile is not thread-safe if a given pathName has to be resolved and/or the file dialog is used. pathName is evaluated if fileNameStr is not a full path to a file.

Example

Variable fileID
NC_OpenFile fileID as "C:Data:test.nc"      // Windows using Macintosh path
NC_OpenFile fileID as "C:\\Data\\test.nc"   // Windows using Windows path
NC_CloseFile fileID

NC_CloseFile [/A /Z ] [refNum ]

Closes a previously opened NetCDF file.

Parameters


refNum	is a number or a numeric variable with the file reference number that was set by NC_OpenFile

Flags


/Z	Prevents aborting of procedure execution if an error occurs.
/A	Closes all open NetCDF files. If /A is used refNum should be omitted.

Output Variables


V_flag	V_flag is set to 0 if no error occurred, otherwise it returns an error code.

Example

Variable fileID
NC_OpenFile fileID as "hd:Data:test.nc"
NC_CloseFile fileID

NC_ListObjects [/Z /Q [/T=typeNameList ] ] refNum

Returns object names from a NetCDF file in a semicolon separated list.

NC_ListObjects returns an error if no object of a given type exists.

Parameters


refNum	is a number or a numeric variable with the file reference number that was set by NC_OpenFile.

Flags

/Z Prevents aborting of procedure execution if an error occurs.

/Q Suppress output to history area.

/T = typeNameList A semicolon separated list of NetCDF object types. Valid types are

dim	dimension names
att	global attribute names
var	variable names
udim	name of unlimited dimension

If /T=typeNameList is omitted NC_ListObjects returns all names as if "dim;att;var;udim;" was given.

Output Variables


V_flag	V_flag is set to 0 if no error occurred, otherwise it returns an error code.
S_names	Returned list of object names

Example

Variable fileID
NC_OpenFile fileID as "hd:Data:test.nc"
NC_ListObjects fileID
NC_ListObjects/T="var" fileID
NC_CloseFile fileID

NC_ListAttributes [/Z /Q ] refNum, [varNameStr ]

Returns attribute names from a NetCDF file in a semicolon separated list.

Parameters


refNum	is a number or a numeric variable with the file reference number that was set by NC_OpenFile.
varNameStr	name of the NetCDF variable for which all attribute names are returned. When omitted the files global attribute names are returned.

Flags


/Z	Prevents aborting of procedure execution if an error occurs.
/Q	Suppress output to history area.

Output Variables


V_flag	V_flag is set to 0 if no error occurred, otherwise it returns an error code.
S_names	Returned list of attribute names

Example

Variable fileID
NC_OpenFile fileID as "hd:Data:test.nc"
NC_ListAttributes fileID                    // Gets global attribute names
NC_ListAttributes fileID, "var"             // Gets attribute names of variable var
NC_CloseFile fileID

NC_Inquire [/Z /Q /A=attNameStr ] refNum, [varNameStr ]

Returns number of dimensions, dimension names and dimension sizes of a NetCDF attribute or variable.

Parameters


refNum	is a number or a numeric variable with the file reference number that was set by NC_OpenFile.
varNameStr	name of a NetCDF variable.
	When combined with /A=attNameStr the attribute of the variable is referenced.
	When varNameStr is omitted /A=attNameStr should be set to refer to a global attribute.

Flags


/Z	Prevents aborting of procedure execution if an error occurs.
/Q	Suppress output to history area.
/A = attNameStr	optional attribute name. Can be combined with varNameStr to refer to an attribute of a variable. If varNameStr is omitted /A refers to a global attribute.

Output Variables


V_flag	V_flag is set to 0 if no error occurred, otherwise it returns an error code.
V_type	Data type of the variable or attribute. See also WaveType for a type code table.
S_names	Semicolon separated list of dimension names of the variable.
	If the variable is scalar (not an array) it has no dimension and S_names is empty.
	In NetCDF attributes have no dimension names. If an attribute is referenced S_names is empty.
S_dims	Semicolon separated list of dimension sizes of the variable or attribute.
	The order of S_names is equal to the order of S_dims. The number of elements in the lists equals the number of dimensions of the variable or attribute. Attributes are always one dimensional.
	Scalar variables (not an array) have no NetCDF dimensions. For such variables S_dims and S_names is an empty String.
	The NetCDF format allows to define a 'unlimited' dimension that grows dynamically. If no data was written to a variable defined with such dimension S_dims return a size of zero.

Example

Variable fileID
NC_OpenFile fileID as "hd:Data:test.nc"
NC_Inquire fileID, "var"                    // Gets information about variable var
NC_Inquire/A="att" fileID, "var"            // Gets information about attribute att of variable var
NC_Inquire/A="gatt" fileID                  // Gets information about global attribute gatt
NC_CloseFile fileID

NC_LoadData [/Z /Q /O /L /U=unpackMode /T=loadType /FREE /DEST=destWave /A[=attNameStr ] /ALL[=loadAll ] ] refNum, [varNameStr ]

Loads an attribute or variable from a NetCDF data set into a wave. If no destination wave reference is given the name of the wave that is created is the same as varNameStr or if omitted as attNameStr. If a wave with this name exists and /O is not set the wave name is changed to a different unique name. Evaluate S_names in such case.

Parameters


refNum	is a number or a numeric variable with the file reference number that was set by NC_OpenFile.
varNameStr	name of a NetCDF variable.
	When combined with /A=attNameStr the attribute of the variable is loaded.
	When varNameStr is omitted /A=attNameStr refers to a global attribute.

Flags

Prevents aborting of procedure execution if an error occurs.

Suppress output to history area.

If a wave with the same name exists it is overwritten.

/DEST = destWave

The data is loaded to the wave referenced by destWave. If /FREE or /O is not specified and destWave exists an error is raised.

/FREE

The data is loaded to a free wave. The wave reference must be given by /DEST=destWave.

/A[ = attNameStr ]

Can be combined with varNameStr to refer to an attribute of a variable. If varNameStr is omitted /A refers to a global attribute.

/A without specifying attNameStr is only allowed in combination with /ALL.

/U = unpackMode

The NetCDF format defines attribute conventions for basic data post processing of variables. Attributes of a variable can be set to enable range checking and data scaling. If these specific attributes are set for the variable NC_LoadData applies range checking and data scaling. The unpackMode flag allows to selectively disable this data post processing.

0:	Range check and data scaling is enabled, same as /U is omitted.
1:	Range check is enabled, data scaling is disabled.
2:	Range check is disabled, data scaling is enabled.
3:	Range check and data scaling is disabled

When data scaling is applied the resulting data type is converted to Float or Double accordingly.

/T = loadType

This flag applies only if the data type of the source variable or attribute is NC_CHAR, it has no effect with other source types. As char data in NetCDF can contain zeroes it is loaded by default to a wave with data type Byte. The /T flag allows to load to a text wave instead.

0:	Loads to a text wave where each element contains a string with a single char. Note that zeroes in the source data will appear as strings with zero length.
1:	Loads to a text wave with a single element that contains a string. This load type works on one dimensional data only. The string in wave[0] might contain zero bytes. Load type 1 is useful when loading variable meta data from attributes such as text descriptions.

When /L is set dimensions are ignored and the variable or attribute is loaded to an one dimensional wave. It is the only way to load high dimensional data that exceeds the maximum number of wave dimensions supported by Igor Pro. The source dimensions can be evaluated from S_dims. The NetCDF XOP does not reorder the data in memory when /L is used.

/ALL[ = loadAll ]

Loads all NetCDF variables and attributes of a file. loadAll can either be 0 or 1, disabling or enabling this feature. /ALL without loadAll flag is identical to loadAll set to 1.

If /A and "varNameStr" is omitted all NetCDF variables, global attributes and variable attributes are loaded.

If /ALL is combined with /A and "varNameStr" is omitted all global NetCDF attributes are loaded.

If /ALL is combined with /A and "varNameStr" is given all NetCDF attributes of the specified NetCDF variable are loaded.

The /ALL option can be combined with /U, /T and /L.

Combining /ALL with one of /DEST, /FREE or /A="attNameStr" raises an error.

When executed from the command line on successful load a summary of loaded waves is printed to the history area. Note that the NetCDF properties are shown. The actual wave could have a different data type if scaling by unpacking (see /U) was applied or different dimension if /L was set.

In case there is an error loading data NC_LoadData stops loading further data and S_names returns empty.

Output Variables


V_flag	V_flag is set to 0 if no error occurred, otherwise it returns an error code.
S_names	Name of the created wave.
	When /ALL was set, semicolon separated list of loaded waves.
S_dims	Semicolon separated list of dimension sizes of the variable or attribute.
	When /ALL was set, S_dims returns an empty string.

Variable Names

If /DEST=waveRef is omitted the name of the resulting wave equals the variable name / global attribute parameter of the operation. The NetCDF library uses normalized UTF-8 encoding for object names. The variable name from Igor is first normalized before accessing a NetCDF object. Thus, denormalized and normalized UTF-8 variable names from Igor target the same object in a NetCDF data set.

Text Data

Source data of the type NC_CHAR can be loaded into an Igor text wave with the /T flag. The NC_CHAR data is assumed to use UTF-8 text encoding. If you know that the source data uses a different text encoding, after loading the data call SetWaveTextEncoding without the /CONV flag to specify the correct text encoding for the text wave's text data.

NetCDF char data can contain null bytes that are transferred to the strings of a text wave. As handling of such strings might be tedious loading without /T as Wave of type byte is recommended for such data.

Scalar Variables

A scalar variable (not an array) has by NetCDF specification no dimensions. S_dims returns an empty String for scalar variables.

Variables with dimension size zero

NetCDF datasets can have one dimension that grows dynamically when data is written. This dimension is called "unlimited dimension". If no data was written the size of this dimension is zero. When loading a variable where at least one dimension size is zero an empty wave is created. This wave has zero dimensions. The actual number of source dimensions and dimension sizes can be read from S_dims.

Attributes with size zero

When loading an empty attribute that has zero size an empty wave is created.

Respected Attribute Conventions

NetCDF defines various attributes for variables with additional information. Respected are the following attributes when set:


units	sets waves data units
long_name	sets wave note
dimension names	sets dimension labels (these are actually in NetCDF no attributes)

Attributes for range check


valid_min	defines the minimum
valid_max	defines the maximum
valid_range	defines the range
_FillValue	defines the maximum if no other limit is set
missing_value	data points exceeding the valid range are treated as missing_value

NC_LoadData respects the NetCDF attribute convention with the following rules:

Data points exceeding the valid range get replaced by missing_value
missing_value must be of the same data type as the source data set
It is treated as error to have valid_range and valid_min or valid_range and valid_max defined.
If _FillValue is defined and neither valid_range nor valid_min nor valid_max is defined then _FillValue sets the maximum of the range.

If range attributes for a variable in the NetCDF file are defined then NC_LoadData sets the data full scale property of the wave accordingly. See also WaveInfo.

Range check can be disabled with /U=2.

Attributes for data scaling


scale_factor	the raw data gets multiplied by scale_factor
add_offset	add_offset is added to the raw data

These attributes are typically used to save data in a smaller data type. Depending on the source data type and the data type of scale_factor and add_offset the resulting wave is of type Float or Double. Thus the scaling may increase the memory footprint. Scaling can be disabled with /U=1.

Example

Variable fileID
NC_OpenFile fileID as "hd:Data:test.nc"
NC_LoadData fileID, "var"                           // Loads variable var
NC_LoadData/A="att" fileID, "var"                   // Loads attribute att of variable var
NC_LoadData/A="gatt" fileID                         // Loads global attribute gatt
NC_LoadData/DEST=ram/FREE/U=3/T=1 fileID, "var"     // Loads variable var which must be of type NC_CHAR
                                                    // into the free text wave ram as a single String in
// element 0, disables unpacking of the data
NC_LoadData/ALL fileID                              // Loads all variables
NC_LoadData/ALL/A fileID, "var"                     // Loads all attributes of variable var
NC_CloseFile fileID

NC_DumpErrors [/C /Q ]

Returns up to the last 128 errors from the NetCDF library. When executed from the command line the error information is dumped to the history area as well.

Flags


/C	Clears the error information after dumping to S_errorInfo
/Q	Suppress output to history area.

Output Variables


S_errorInfo	Collected error messages from the NetCDF library. The format is
	codeerrorMessage.

Example

Variable fileID
NC_OpenFile fileID as "hd:Data:test.nc"
// Do NetCDF things here
NC_DumpErrors/C                 // Retrieve collected error information
print S_errorInfo
NC_CloseFile fileID

NC_OpenFile [/Z /I /PATH=pathName ] refNum [as fileNameStr ]​

Parameters​

Flags​

Output Variables​

Thread Safety​

Example​

See Also​

NC_CloseFile [/A /Z ] [refNum ]​

Parameters​

Flags​

Output Variables​

Example​

See Also​

NC_ListObjects [/Z /Q [/T=typeNameList ] ] refNum​

Parameters​

Flags​

Output Variables​

Example​

See Also​

NC_ListAttributes [/Z /Q ] refNum, [varNameStr ]​

Parameters​

Flags​

Output Variables​

Example​

See Also​

NC_Inquire [/Z /Q /A=attNameStr ] refNum, [varNameStr ]​

Parameters​

Flags​

Output Variables​

Example​

See Also​

NC_LoadData [/Z /Q /O /L /U=unpackMode /T=loadType /FREE /DEST=destWave /A[=attNameStr ] /ALL[=loadAll ] ] refNum, [varNameStr ]​

Parameters​

Flags​

Output Variables​

Variable Names​

Text Data​

Scalar Variables​

Variables with dimension size zero​

Attributes with size zero​

Respected Attribute Conventions​

Attributes for range check​

Attributes for data scaling​

Example​

See Also​

NC_DumpErrors [/C /Q ]​

Flags​

Output Variables​

Example​

See Also​

NC_OpenFile [/Z /I /PATH=pathName ] refNum [as fileNameStr ]

Parameters

Flags

Output Variables

Thread Safety

Example

See Also

NC_CloseFile [/A /Z ] [refNum ]

Parameters

Flags

Output Variables

Example

See Also

NC_ListObjects [/Z /Q [/T=typeNameList ] ] refNum

Parameters

Flags

Output Variables

Example

See Also

NC_ListAttributes [/Z /Q ] refNum, [varNameStr ]

Parameters

Flags

Output Variables

Example

See Also

NC_Inquire [/Z /Q /A=attNameStr ] refNum, [varNameStr ]

Parameters

Flags

Output Variables

Example

See Also

NC_LoadData [/Z /Q /O /L /U=unpackMode /T=loadType /FREE /DEST=destWave /A[=attNameStr ] /ALL[=loadAll ] ] refNum, [varNameStr ]

Parameters

Flags

Output Variables

Variable Names

Text Data

Scalar Variables

Variables with dimension size zero

Attributes with size zero

Respected Attribute Conventions

Attributes for range check

Attributes for data scaling

Example

See Also

NC_DumpErrors [/C /Q ]

Flags

Output Variables

Example

See Also