NetCDF  4.6.3
 All Data Structures Files Functions Variables Typedefs Macros Modules Pages
notes.md
1 # NetCDF Programming Notes {#programming_notes}
2 
3 [TOC]
4 
5 <H2>See Also:</H2>
6 
7 * \subpage nc-error-codes
8 
9 # Ignored if NULL {#ignored_if_null}
10 
11 Many of the argurments of netCDF functions are pointers. For example,
12 the nc_inq() functions takes four pointers:
13 
14 ~~~.C
15 int nc_inq(int ncid, int *ndimsp, int *nvarsp, int *nattsp, int *unlimdimidp);
16 ~~~
17 
18 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:
19 
20 ~~~.C
21 int ndims;
22 ...
23 if (nc_inq(ncid, &ndims, NULL, NULL, NULL))
24  return SOME_ERROR;
25 ~~~
26 
27 # Allocating Storage for the Result {#allocating_storage_for_the_result}
28 
29 User must allocate space for the result of an inq function before the function is called.
30 
31 # Specify a Hyperslab {#specify_hyperslab}
32 
33 The NetCDF allows specification of hyperslabs to be read or written
34 with vectors which specify the start, count, stride, and mapping.
35 
36 ## A Vector Specifying Start Index for Each Dimension {#start_vector}
37 
38 A vector of size_t integers specifying the index in the
39 variable where the first of the data values will be read.
40 
41 The indices are relative to 0, so for example, the first data value of
42 a variable would have index (0, 0, ... , 0).
43 
44 The length of start vector must be the same as the number of
45 dimensions of the specified variable. The elements of start
46 correspond, in order, to the variable's dimensions.
47 
48 ## A Vector Specifying Count for Each Dimension {#count_vector}
49 
50 A vector of size_t integers specifying the edge lengths
51 along each dimension of the block of data values to be read.
52 
53 To read a single value, for example, specify count as (1, 1, ... , 1).
54 
55 The length of count is the number of dimensions of the specified
56 variable. The elements of count correspond, in order, to the
57 variable's dimensions.
58 
59 Setting any element of the count array to zero causes the function to
60 exit without error, and without doing anything.
61 
62 ## A Vector Specifying Stride for Each Dimension {#stride_vector}
63 
64 A vector of size_t integers specifying the interval between selected
65 indices.
66 
67 A value of 1 accesses adjacent values of the netCDF variable in the
68 corresponding dimension; a value of 2 accesses every other value of
69 the netCDF variable in the corresponding dimension; and so on.
70 
71 The elements of the stride vector correspond, in order, to the
72 variable's dimensions.
73 
74 A NULL stride argument is treated as (1, 1, ... , 1).
75 
76 ## A Vector Specifying Mapping for Each Dimension {#map_vector}
77 
78 A vector of integers that specifies the mapping between the dimensions
79 of a netCDF variable and the in-memory structure of the internal data
80 array.
81 
82 imap[0] gives the distance between elements of the internal array
83 corresponding to the most slowly varying dimension of the netCDF
84 variable. imap[n-1] (where n is the rank of the netCDF variable) gives
85 the distance between elements of the internal array corresponding to
86 the most rapidly varying dimension of the netCDF variable. Intervening
87 imap elements correspond to other dimensions of the netCDF variable in
88 the obvious way. Distances between elements are specified in
89 type-independent units of elements.
90 
91 \note The distance between internal elements that occupy adjacent
92 memory locations is 1 and not the element's byte-length as in netCDF
93 2.
94 
95 # NetCDF ID {#ncid}
96 
97 Most netCDF function require the netCDF ID as a first parameter.
98 
99 In the netCDF classic model, the netCDF ID is associated with an open
100 file. Each file, when opened by nc_open(), or created by nc_create(),
101 is assigned an ncid, which it retains until nc_close() is called.
102 
103 In the netCDF enhanced model, the ncid refers to a group with a
104 file. (Each file contains at least the root group, which is the ncid
105 that is returned by nc_open() and nc_create().)
106 
107 For netCDF-4/HDF5 files, netCDF IDs can come not just from nc_open()
108 and nc_create(), but also from nc_def_grp(), nc_inq_grps(),
109 nc_inq_ncid(), nc_inq_grp_parent(), and nc_inq_grp_full_ncid().

Return to the Main Unidata NetCDF page.
Generated on Sat Apr 6 2019 08:19:00 for NetCDF. NetCDF is a Unidata library.