NetCDF  4.9.2
notes.md
1 # NetCDF Programming Notes {#programming_notes}
2 
3 [TOC]
4 
5 <H2>See Also:</H2>
6 
7 # Ignored if NULL {#ignored_if_null}
8 
9 Many of the argurments of netCDF functions are pointers. For example,
10 the nc_inq() functions takes four pointers:
11 
12 ~~~.C
13 int nc_inq(int ncid, int *ndimsp, int *nvarsp, int *nattsp, int *unlimdimidp);
14 ~~~
15 
16 A NULL may be passed for any of these pointers, and it will be ignored. For example, interested in the number of dimensions only, the following code will work:
17 
18 ~~~.C
19 int ndims;
20 ...
21 if (nc_inq(ncid, &ndims, NULL, NULL, NULL))
22  return SOME_ERROR;
23 ~~~
24 
25 # Allocating Storage for the Result {#allocating_storage_for_the_result}
26 
27 User must allocate space for the result of an inq function before the function is called.
28 
29 # Specify a Hyperslab {#specify_hyperslab}
30 
31 The NetCDF allows specification of hyperslabs to be read or written
32 with vectors which specify the start, count, stride, and mapping.
33 
34 ## A Vector Specifying Start Index for Each Dimension {#start_vector}
35 
36 A vector of size_t integers specifying the index in the
37 variable where the first of the data values will be read.
38 
39 The indices are relative to 0, so for example, the first data value of
40 a variable would have index (0, 0, ... , 0).
41 
42 The length of start vector must be the same as the number of
43 dimensions of the specified variable. The elements of start
44 correspond, in order, to the variable's dimensions.
45 
46 ## A Vector Specifying Count for Each Dimension {#count_vector}
47 
48 A vector of size_t integers specifying the edge lengths
49 along each dimension of the block of data values to be read.
50 
51 To read a single value, for example, specify count as (1, 1, ... , 1).
52 
53 The length of count is the number of dimensions of the specified
54 variable. The elements of count correspond, in order, to the
55 variable's dimensions.
56 
57 Setting any element of the count array to zero causes the function to
58 exit without error, and without doing anything.
59 
60 ## A Vector Specifying Stride for Each Dimension {#stride_vector}
61 
62 A vector of size_t integers specifying the interval between selected
63 indices.
64 
65 A value of 1 accesses adjacent values of the netCDF variable in the
66 corresponding dimension; a value of 2 accesses every other value of
67 the netCDF variable in the corresponding dimension; and so on.
68 
69 The elements of the stride vector correspond, in order, to the
70 variable's dimensions.
71 
72 A NULL stride argument is treated as (1, 1, ... , 1).
73 
74 ## A Vector Specifying Mapping for Each Dimension {#map_vector}
75 
76 A vector of integers that specifies the mapping between the dimensions
77 of a netCDF variable and the in-memory structure of the internal data
78 array.
79 
80 imap[0] gives the distance between elements of the internal array
81 corresponding to the most slowly varying dimension of the netCDF
82 variable. imap[n-1] (where n is the rank of the netCDF variable) gives
83 the distance between elements of the internal array corresponding to
84 the most rapidly varying dimension of the netCDF variable. Intervening
85 imap elements correspond to other dimensions of the netCDF variable in
86 the obvious way. Distances between elements are specified in
87 type-independent units of elements.
88 
89 \note The distance between internal elements that occupy adjacent
90 memory locations is 1 and not the element's byte-length as in netCDF
91 2.
92 
93 # NetCDF ID {#ncid}
94 
95 Most netCDF function require the netCDF ID as a first parameter.
96 
97 In the netCDF classic model, the netCDF ID is associated with an open
98 file. Each file, when opened by nc_open(), or created by nc_create(),
99 is assigned an ncid, which it retains until nc_close() is called.
100 
101 In the netCDF enhanced model, the ncid refers to a group with a
102 file. (Each file contains at least the root group, which is the ncid
103 that is returned by nc_open() and nc_create().)
104 
105 For netCDF-4/HDF5 files, netCDF IDs can come not just from nc_open()
106 and nc_create(), but also from nc_def_grp(), nc_inq_grps(),
107 nc_inq_ncid(), nc_inq_grp_parent(), and nc_inq_grp_full_ncid().
108 
109 # NetCDF Names {#object_name}
110 
111 ## Permitted Characters in NetCDF Names
112 
113 The names of dimensions, variables and attributes (and, in netCDF-4
114 files, groups, user-defined types, compound member names, and
115 enumeration symbols) consist of arbitrary sequences of alphanumeric
116 characters, underscore '_', period '.', plus '+', hyphen '-', or at
117 sign '@', but beginning with an alphanumeric character or
118 underscore. However names commencing with underscore are reserved for
119 system use.
120 
121 Beginning with versions 3.6.3 and 4.0, names may also include UTF-8
122 encoded Unicode characters as well as other special characters, except
123 for the character '/', which may not appear in a name.
124 
125 Names that have trailing space characters are also not permitted.
126 
127 Case is significant in netCDF names.
128 
129 ## Name Length
130 
131 A zero-length name is not allowed.
132 
133 Names longer than ::NC_MAX_NAME will not be accepted any netCDF define
134 function. An error of ::NC_EMAXNAME will be returned.
135 
136 All netCDF inquiry functions will return names of maximum size
137 ::NC_MAX_NAME for netCDF files. Since this does not include the
138 terminating NULL, space should be reserved for ::NC_MAX_NAME + 1
139 characters.
140 
141 ## NetCDF Conventions
142 
143 Some widely used conventions restrict names to only alphanumeric
144 characters or underscores.
145 
146 Note that, when using the DAP2 protocol to access netCDF data, there
147 are reserved keywords, the use of which may result in undefined
148 behavior. See DAP2 Reserved Keywords for more information.