1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
|
<!-- Generated by Harlequin WebMaker 2.2.3 (24-Apr-1996)
LispWorks 3.2.2 -->
<HTML> <HEAD>
<TITLE>6 Dimensions</TITLE>
</HEAD>
<BODY bgcolor="#ffffff">
<A NAME=HEADING11></A>
<A HREF="guidef-12.html">[Next] </A><A HREF="guidef-10.html">[Previous] </A><A HREF="guidef-1.html">[Top] </A><A HREF="guidef-3.html">[Contents] </A><A HREF="guidef-21.html">[Index] </A><A HREF="http://www.unidata.ucar.edu/packages/netcdf/">[netCDF Home Page]</A><A HREF="http://www.unidata.ucar.edu/">[Unidata Home Page]</A><P>
NetCDF User's Guide for Fortran<P>
<A NAME=HEADING11-0></A>
<H1>6 Dimensions</H1>
<HR>
Dimensions <A NAME=MARKER-2-2308></A>for a netCDF dataset are defined when it is created, while the netCDF dataset is in define mode. Additional dimensions may be added later by reentering define mode. A netCDF dimension has a name and a length. At most one dimension in a netCDF dataset can have the <CODE>unlimited</CODE> length, which means variables using this dimension can grow along this dimension. <P>
There <A NAME=MARKER-2-2309></A><A NAME=MARKER-2-2310></A>is a suggested limit (100) to the number of dimensions that can be defined in a single netCDF dataset. The limit is the value of the predefined macro <A NAME=MARKER-10-2316></A><CODE><A NAME=MARKER-2-2317></A>NF_MAX_DIMS</CODE>. The purpose of the limit is to make writing generic applications simpler. They need only provide an array of <A NAME=MARKER-10-2318></A><CODE>NF_MAX_DIMS</CODE> dimensions to handle any netCDF dataset. The implementation of the netCDF library does not enforce this advisory maximum, so it is possible to use more dimensions, if necessary, but netCDF utilities that assume the advisory maximums may not be able to handle the resulting netCDF datasets. <P>
Ordinarily, the name and length of a dimension are fixed when the dimension is first defined. The name may be changed later, but the length of a dimension (other than the unlimited dimension) cannot be changed without copying all the data to a new netCDF dataset with a redefined dimension length. <P>
<A NAME=MARKER-10-2323></A>A netCDF dimension in an open netCDF dataset is referred to by a small integer called a <I>dimension ID</I>. In the <A NAME=MARKER-10-2326></A>FORTRAN interface, dimension IDs are <A NAME=MARKER-10-2327></A>1, <A NAME=MARKER-10-2328></A>2, <A NAME=MARKER-10-2329></A>3, ..., in the order in which the dimensions were defined. <P>
Operations supported on dimensions are:<P>
<UL>
<LI>Create a dimension, given its name and length.<P>
<LI>Get a dimension ID from its name.<P>
<LI>Get a dimension's name and length from its ID.<P>
<LI>Rename a dimension.<P>
</UL>
<A NAME=HEADING11-10></A>
<H2>6.1 Create a Dimension: <A NAME=MARKER-10-2330></A><CODE><A NAME=MARKER-2-2331></A>NF_DEF_DIM </CODE></H2>
<HR>
The <A NAME=MARKER-2-2342></A><A NAME=MARKER-2-2343></A><A NAME=MARKER-2-2344></A>function <A NAME=MARKER-10-2345></A><CODE>NF_DEF_DIM</CODE> adds a new dimension to an open netCDF dataset in define mode. It returns (as an argument) a dimension ID, given the netCDF ID, the dimension name, and the dimension length. At most one unlimited length dimension, called the record dimension, may be defined for each netCDF dataset.<P>
<A NAME=HEADING11-12></A>
<H4>Usage </H4>
<PRE>
<A NAME=MARKER-10-2346></A>INTEGER FUNCTION NF_DEF_DIM (INTEGER NCID, CHARACTER*(*) NAME,
INTEGER LEN, INTEGER dimid)
<TABLE BORDER="1"><TD><CODE>NCID</CODE><TD>NetCDF ID, from a previous call to <CODE>NF_OPEN</CODE> or <CODE>NF_CREATE</CODE>.<TR>
<TD><CODE>NAME</CODE><TD>Dimension name. Must begin with an alphabetic character, followed by zero or more alphanumeric characters including the underscore ('<CODE>_</CODE>'). Case is significant.<TR>
<TD><CODE>LEN</CODE><TD>Length of dimension; that is, number of values for this dimension as an index to variables that use it. This should be either a positive integer or the predefined constant <CODE><A NAME=MARKER-2-162></A>NF_UNLIMITED</CODE>.<TR>
<TD><CODE>dimid</CODE><TD>Returned dimension ID.</TABLE>
</PRE>
Errors <P>
<CODE><A NAME=MARKER-10-2347></A>NF_DEF_DIM</CODE> returns the value <A NAME=MARKER-10-2348></A><CODE>NF_NOERR</CODE> if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include: <P>
<UL>
<LI>The netCDF dataset is not in definition mode.<P>
<LI>The specified dimension name is the name of another existing dimension.<P>
<LI>The specified length is not greater than zero.<P>
<LI>The specified length is unlimited, but there is already an unlimited length dimension defined for this netCDF dataset.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING11-22></A>
<H4>Example </H4>
Here <A NAME=MARKER-10-2350></A>is an example using <A NAME=MARKER-10-2351></A><CODE>NF_DEF_DIM</CODE> to create a dimension named <CODE>lat</CODE> of length 18 and a unlimited dimension named <CODE>rec</CODE> in a new netCDF dataset named <CODE>foo.nc</CODE>:<P>
<PRE>
<A NAME=MARKER-10-2352></A>INCLUDE 'netcdf.inc'
...
INTEGER STATUS, NCID, LATID, RECID
...
STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_DEF_DIM(NCID, 'lat', 18, LATID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_DEF_DIM(NCID, 'rec', NF_UNLIMITED, RECID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
</PRE>
<A NAME=HEADING11-35></A>
<H2>6.2 Get a Dimension ID from Its Name: <A NAME=MARKER-10-2353></A><CODE><A NAME=MARKER-3-2354></A>NF_INQ_DIMID </CODE></H2>
<HR>
The <A NAME=MARKER-2-2359></A><A NAME=MARKER-2-2360></A><A NAME=MARKER-2-2361></A>function <A NAME=MARKER-10-2362></A><CODE>NF_INQ_DIMID</CODE> returns (as an argument) the ID of a netCDF dimension, given the name of the dimension. If <CODE>ndims</CODE> is the number of dimensions defined for a netCDF dataset, each dimension has an ID between <A NAME=MARKER-10-2363></A>1 and <A NAME=MARKER-10-2364></A><CODE>ndims.</CODE><P>
<A NAME=HEADING11-37></A>
<H4>Usage </H4>
<PRE>
<A NAME=MARKER-10-2365></A>INTEGER FUNCTION NF_INQ_DIMID (INTEGER NCID, CHARACTER*(*) NAME,
INTEGER dimid)
<TABLE BORDER="1"><TD><CODE>NCID</CODE><TD>NetCDF ID, from a previous call to <CODE>NF_OPEN</CODE> or <CODE>NF_CREATE</CODE>.<TR>
<TD><CODE>NAME</CODE><TD>Dimension name, a character string beginning with a letter and followed by any sequence of letters, digits, or underscore ('<CODE>_</CODE>') characters. Case is significant in dimension names.<TR>
<TD><CODE>dimid</CODE><TD>Returned dimension ID.</TABLE>
</PRE>
Errors <P>
<CODE><A NAME=MARKER-10-2366></A>NF_INQ_DIMID</CODE> returns the value <A NAME=MARKER-10-2367></A><CODE>NF_NOERR</CODE> if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include: <P>
<UL>
<LI>The name that was specified is not the name of a dimension in the netCDF dataset.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING11-44></A>
<H4>Example </H4>
Here <A NAME=MARKER-10-2369></A>is an example using <A NAME=MARKER-10-2370></A><CODE><A NAME=MARKER-10-2371></A>NF_INQ_DIMID</CODE> to determine the dimension ID of a dimension named <CODE>lat</CODE>, assumed to have been defined previously in an existing netCDF dataset named <CODE>foo.nc</CODE>:<P>
<PRE>
<A NAME=MARKER-10-2372></A>INCLUDE 'netcdf.inc'
...
INTEGER STATUS, NCID, LATID
...
STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_INQ_DIMID(NCID, 'lat', LATID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
</PRE>
<A NAME=HEADING11-55></A>
<H2>6.3 Inquire about a Dimension: <A NAME=MARKER-10-2373></A><CODE><A NAME=MARKER-2-2374></A>NF_INQ_DIM</CODE> Family</H2>
<HR>
This <A NAME=MARKER-2-2379></A><A NAME=MARKER-2-2380></A><A NAME=MARKER-2-2381></A><A NAME=MARKER-2-2382></A><A NAME=MARKER-2-2383></A><A NAME=MARKER-2-2384></A><A NAME=MARKER-2-2385></A><A NAME=MARKER-2-2386></A><A NAME=MARKER-2-2387></A><A NAME=MARKER-2-2388></A><A NAME=MARKER-2-2389></A><A NAME=MARKER-2-2390></A><A NAME=MARKER-2-2391></A><A NAME=MARKER-2-2396></A><A NAME=MARKER-2-2397></A><A NAME=MARKER-2-2398></A><A NAME=MARKER-2-2399></A><A NAME=MARKER-2-2400></A><A NAME=MARKER-2-2401></A>family of functions returns information about a netCDF dimension. Information about a dimension includes its name and its length. The length for the unlimited dimension, if any, is the number of records written so far. <P>
The functions in this family include <A NAME=MARKER-10-2402></A><CODE>NF_INQ_DIM</CODE>, <CODE><A NAME=MARKER-10-2403></A><A NAME=MARKER-2-2404></A>NF_INQ_DIMNAME</CODE>, and<A NAME=MARKER-10-2405></A> <A NAME=MARKER-10-2406></A><CODE><A NAME=MARKER-2-2407></A>NF_INQ_DIMLEN</CODE>. The function <CODE><A NAME=MARKER-10-2408></A>NF_INQ_DIM</CODE> returns all the information about a dimension; the other functions each return just one item of information. <P>
<A NAME=HEADING11-58></A>
<H4>Usage </H4>
<PRE>
<A NAME=MARKER-10-2409></A>INTEGER FUNCTION NF_INQ_DIM (INTEGER NCID, INTEGER DIMID,
CHARACTER*(*) name, INTEGER len)
INTEGER FUNCTION NF_INQ_DIMNAME (INTEGER NCID, INTEGER DIMID,
CHARACTER*(*) name)
INTEGER FUNCTION NF_INQ_DIMLEN (INTEGER NCID, INTEGER DIMID,
INTEGER len)
<TABLE BORDER="1"><TD><CODE>NCID</CODE><TD>NetCDF ID, from a previous call to <CODE>NF_OPEN</CODE> or <CODE>NF_CREATE</CODE>.<TR>
<TD><CODE>DIMID</CODE><TD>Dimension ID, for example from a previous call to <CODE><A NAME=MARKER-3-2354></A>NF_INQ_DIMID</CODE> or <CODE>NF_DEF_DIM</CODE>.<TR>
<TD><CODE>name</CODE><TD>Returned dimension name. The caller must allocate space for the returned name. The maximum possible length, in characters, of a dimension name is given by the predefined constant <CODE>NF_MAX_NAME</CODE>.<TR>
<TD><CODE>len</CODE><TD>Returned length of dimension. For the unlimited dimension, this is the current maximum value used for writing any variables with this dimension, that is the maximum record number.</TABLE>
</PRE>
Errors <P>
These functions return the value <A NAME=MARKER-10-2410></A><CODE>NF_NOERR</CODE> if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The dimension ID is invalid for the specified netCDF dataset.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING11-69></A>
<H4>Example </H4>
Here <A NAME=MARKER-10-2412></A>is an example using <A NAME=MARKER-10-2413></A><CODE>NF_INQ_DIM</CODE> to determine the length of a dimension named <CODE>lat</CODE>, and the name and current maximum length of the unlimited dimension for an existing netCDF dataset named <CODE>foo.nc</CODE>:<P>
<PRE>
<A NAME=MARKER-10-2414></A>INCLUDE 'netcdf.inc'
...
INTEGER STATUS, NCID, LATID, LATLEN, RECID, NRECS
CHARACTER*(NF_MAX_NAME) LATNAM, RECNAM
...
STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
! get ID of unlimited dimension
STATUS = NF_INQ_UNLIMDIM(NCID, RECID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
STATUS = NF_INQ_DIMID(NCID, 'lat', LATID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
! get lat length
STATUS = NF_INQ_DIMLEN(NCID, LATID, LATLEN)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
! get unlimited dimension name and current length
STATUS = NF_INQ_DIM(NCID, RECID, RECNAME, NRECS)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
</PRE>
<A NAME=HEADING11-90></A>
<H2>6.4 Rename a Dimension: <A NAME=MARKER-10-2415></A><CODE><A NAME=MARKER-2-2416></A>NF_RENAME_DIM </CODE></H2>
<HR>
The <A NAME=MARKER-2-2417></A><A NAME=MARKER-2-2418></A><A NAME=MARKER-2-2419></A><A NAME=MARKER-2-2420></A>function <A NAME=MARKER-10-2421></A><CODE>NF_RENAME_DIM</CODE> renames an existing dimension in a netCDF dataset open for writing. If the new name is longer than the old name, the netCDF dataset must be in define mode. You cannot rename a dimension to have the same name as another dimension. <P>
<A NAME=HEADING11-92></A>
<H4>Usage </H4>
<PRE>
<A NAME=MARKER-10-2422></A>INTEGER FUNCTION NF_RENAME_DIM (INTEGER NCID, INTEGER DIMID,
CHARACTER*(*) NAME)
<TABLE BORDER="1"><TD>NCID<TD>NetCDF ID, from a previous call to <CODE>NF_OPEN</CODE> or <CODE>NF_CREATE</CODE>.<TR>
<TD>DIMID<TD>Dimension ID, from a previous call to <CODE>NF_INQ_DIMID</CODE> or <CODE>NF_DEF_DIM</CODE>.<TR>
<TD>NAME<TD>New name for the dimension.</TABLE>
</PRE>
Errors <P>
<CODE><A NAME=MARKER-10-2423></A>NF_RENAME_DIM</CODE> returns the value <A NAME=MARKER-10-2424></A><CODE>NF_NOERR</CODE> if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include: <P>
<UL>
<LI>The new name is the name of another dimension.<P>
<LI>The dimension ID is invalid for the specified netCDF dataset.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
<LI>The new name is longer than the old name and the netCDF dataset is not in define mode.<P>
</UL>
<A NAME=HEADING11-101></A>
<H4>Example </H4>
Here <A NAME=MARKER-10-2426></A>is an example using <A NAME=MARKER-10-2427></A><CODE>NF_RENAME_DIM</CODE> to rename the dimension <CODE>lat</CODE> to <CODE>latitude</CODE> in an existing netCDF dataset named <CODE>foo.nc</CODE>:<P>
<PRE>
<A NAME=MARKER-10-2428></A>INCLUDE 'netcdf.inc'
...
INTEGER STATUS, NCID, LATID
...
STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
...
! put in define mode to rename dimension
STATUS = NF_REDEF(NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_INQ_DIMID(NCID, 'lat', LATID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
STATUS = NF_RENAME_DIM(NCID, LATID, 'latitude')
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
! leave define mode
STATUS = NF_ENDDEF(NCID)
IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
</PRE>
<!-- TOC --><DL>
<DT><A HREF="guidef-11.html#HEADING11-10"><B>6.1 </B> - Create a Dimension: NF_DEF_DIM </A>
<DD>
<DT><A HREF="guidef-11.html#HEADING11-12"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidef-11.html#HEADING11-22"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidef-11.html#HEADING11-35"><B>6.2 </B> - Get a Dimension ID from Its Name: NF_INQ_DIMID </A>
<DD>
<DT><A HREF="guidef-11.html#HEADING11-37"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidef-11.html#HEADING11-44"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidef-11.html#HEADING11-55"><B>6.3 </B> - Inquire about a Dimension: NF_INQ_DIM Family</A>
<DD>
<DT><A HREF="guidef-11.html#HEADING11-58"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidef-11.html#HEADING11-69"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidef-11.html#HEADING11-90"><B>6.4 </B> - Rename a Dimension: NF_RENAME_DIM </A>
<DD>
<DT><A HREF="guidef-11.html#HEADING11-92"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidef-11.html#HEADING11-101"><B>Example</B> - </A>
<DD>
</DL>
<HR>
<ADDRESS>NetCDF User's Guide for Fortran - 4 JUN 1997</ADDRESS>
<A HREF="guidef-12.html">[Next] </A><A HREF="guidef-10.html">[Previous] </A><A HREF="guidef-1.html">[Top] </A><A HREF="guidef-3.html">[Contents] </A><A HREF="guidef-21.html">[Index] </A><A HREF="http://www.unidata.ucar.edu/packages/netcdf/">[netCDF Home Page]</A><A HREF="http://www.unidata.ucar.edu/">[Unidata Home Page]</A><P>
</BODY>
|
