NetCDF-Fortran  4.4.2
netcdf-f77.md
1 The NetCDF Fortran 77 Interface Guide {#nc_f77_interface_guide}
2 =====================================
3 
4 [TOC]
5 
6 This document describes the FORTRAN-77 interface to the netCDF library.
7 
8 1 Use of the NetCDF Library {#Use_of_the_NetCDF_Library}
9 =============================
10 
11 You can use the netCDF library without knowing about all of the netCDF
12 interface. If you are creating a netCDF dataset, only a handful of
13 routines are required to define the necessary dimensions, variables, and
14 attributes, and to write the data to the netCDF dataset. (Even less are
15 needed if you use the ncgen utility to create the dataset before running
16 a program using netCDF library calls to write data. See
17 section ‘ncgen’ in The NetCDF Users
18 Guide.) Similarly, if you are writing software to access data stored in
19 a particular netCDF object, only a smallbset of the netCDF library is
20 required to open the netCDF dataset and access the data. Authors of
21 generic applications that access arbitrary netCDF datasets need to be
22 familiar with more of the netCDF library.
23 
24 In this we provide templates of common sequences of netCDF calls
25 needed for common uses. For clarity we present only the names of
26 routines; omit declarations and error checking; omit the type-specific
27 suffixes of routine names for variables and attributes; indent
28 statements that are typically invoked multiple times; and use ... to
29 represent arbitrary sequences of other statements. Full parameter lists
30 are described in laters.
31 
32 
33 
34 1.1 Creating a NetCDF Dataset {#Creating_a_NetCDF_Dataset}
35 -----------------------------
36 
37 Here is a typical sequence of netCDF calls used to create a new netCDF
38 dataset:
39 
40  
41 
42 
43  NF_CREATE ! create netCDF dataset: enter define mode
44  ...
45  NF_DEF_DIM ! define dimensions: from name and length
46  ...
47  NF_DEF_VAR ! define variables: from name, type, dims
48  ...
49  NF_PUT_ATT ! assign attribute values
50  ...
51  NF_ENDDEF ! end definitions: leave define mode
52  ...
53  NF_PUT_VAR ! provide values for variable
54  ...
55  NF_CLOSE ! close: save new netCDF dataset
56 
57 
58 Only one call is needed to create a netCDF dataset, at which point you
59 will be in the first of two netCDF modes. When accessing an open netCDF
60 dataset, it is either in define mode or data mode. In define mode, you
61 can create dimensions, variables, and new attributes, but you cannot
62 read or write variable data. In data mode, you can access data and
63 change existing attributes, but you are not permitted to create new
64 dimensions, variables, or attributes.
65 
66 One call to NF\_DEF\_DIM is needed for each dimension created.
67 Similarly, one call to NF\_DEF\_VAR is needed for each variable
68 creation, and one call to a member of the NF\_PUT\_ATT family is needed
69 for each attribute defined and assigned a value. To leave define mode
70 and enter data mode, call NF\_ENDDEF.
71 
72 Once in data mode, you can add new data to variables, change old values,
73 and change values of existing attributes (so long as the attribute
74 changes do not require more storage space). Single values may be written
75 to a netCDF variable with one of the members of the NF\_PUT\_VAR1
76 family, depending on what type of data you have to write. All the values
77 of a variable may be written at once with one of the members of the
78 NF\_PUT\_VAR family. Arrays or array crosss of a variable may be
79 written using members of the NF\_PUT\_VARA family. Subsampled array
80 sections may be written using members of the NF\_PUT\_VARS family.
81 Mapped arrays may be written using members of the NF\_PUT\_VARM
82 family. (Subsampled and mapped access are general forms of data access
83 that are explained later.)
84 
85 Finally, you should explicitly close all netCDF datasets that have been
86 opened for writing by calling NF\_CLOSE. By default, access to the file
87 system is buffered by the netCDF library. If a program terminates
88 abnormally with netCDF datasets open for writing, your most recent
89 modifications may be lost. This default buffering of data is disabled by
90 setting the NF\_SHARE flag when opening the dataset. But even if this
91 flag is set, changes to attribute values or changes made in define mode
92 are not written out until NF\_SYNC or NF\_CLOSE is called.
93 
94 1.2 Reading a NetCDF Dataset with Known Names {#Reading_a_NetCDF_Dataset_with_Known_Names}
95 ---------------------------------------------
96 
97 Here we consider the case where you know the names of not only the
98 netCDF datasets, but also the names of their dimensions, variables, and
99 attributes. (Otherwise you would have to do "inquire" calls.) The order
100 of typical C calls to read data from those variables in a netCDF dataset
101 is:
102 
103  
104 
105 
106  NF_OPEN ! open existing netCDF dataset
107  ...
108  NF_INQ_DIMID ! get dimension IDs
109  ...
110  NF_INQ_VARID ! get variable IDs
111  ...
112  NF_GET_ATT ! get attribute values
113  ...
114  NF_GET_VAR ! get values of variables
115  ...
116  NF_CLOSE ! close netCDF dataset
117 
118 
119 First, a single call opens the netCDF dataset, given the dataset name,
120 and returns a netCDF ID that is used to refer to the open netCDF dataset
121 in allbsequent calls.
122 
123 Next, a call to NF\_INQ\_DIMID for each dimension of interest gets the
124 dimension ID from the dimension name. Similarly, each required variable
125 ID is determined from its name by a call to NF\_INQ\_VARID.Once variable
126 IDs are known, variable attribute values can be retrieved using the
127 netCDF ID, the variable ID, and the desired attribute name as input to a
128 member of the NF\_GET\_ATT family (typically NF\_GET\_ATT\_TEXT or
129 NF\_GET\_ATT\_DOUBLE) for each desired attribute. Variable data values
130 can be directly accessed from the netCDF dataset with calls to members
131 of the NF\_GET\_VAR1 family for single values, the NF\_GET\_VAR family
132 for entire variables, or various other members of the NF\_GET\_VARA,
133 NF\_GET\_VARS, or NF\_GET\_VARM families for array,bsampled or mapped
134 access.
135 
136 Finally, the netCDF dataset is closed with NF\_CLOSE. There is no need
137 to close a dataset open only for reading.
138 
139 
140 1.3 Reading a netCDF Dataset with Unknown Names {#Reading_a_netCDF_Dataset_with_Unknown_Names}
141 -----------------------------------------------
142 
143 It is possible to write programs (e.g., generic software) which doch
144 things as processing every variable, without needing to know in advance
145 the names of these variables. Similarly, the names of dimensions and
146 attributes may be unknown.
147 
148 Names and other information about netCDF objects may be obtained from
149 netCDF datasets by calling inquire functions. These return information
150 about a whole netCDF dataset, a dimension, a variable, or an attribute.
151 The following template illustrates how they are used:
152 
153  
154 
155 
156  NF_OPEN ! open existing netCDF dataset
157  ...
158  NF_INQ ! find out what is in it
159  ...
160  NF_INQ_DIM ! get dimension names, lengths
161  ...
162  NF_INQ_VAR ! get variable names, types, shapes
163  ...
164  NF_INQ_ATTNAME ! get attribute names
165  ...
166  NF_INQ_ATT ! get attribute values
167  ...
168  NF_GET_ATT ! get attribute values
169  ...
170  NF_GET_VAR ! get values of variables
171  ...
172  NF_CLOSE ! close netCDF dataset
173 
174 
175 As in the previous example, a single call opens the existing netCDF
176 dataset, returning a netCDF ID. This netCDF ID is given to the NF\_INQ
177 routine, which returns the number of dimensions, the number of
178 variables, the number of global attributes, and the ID of the unlimited
179 dimension, if there is one.
180 
181 All the inquire functions are inexpensive to use and require no I/O,
182 since the information they provide is stored in memory when a netCDF
183 dataset is first opened.
184 
185 Dimension IDs use consecutive integers, beginning at 1. Also dimensions,
186 once created, cannot be deleted. Therefore, knowing the number of
187 dimension IDs in a netCDF dataset means knowing all the dimension IDs:
188 they are the integers 1, 2, 3, ... up to the number of dimensions. For
189 each dimension ID, a call to the inquire function NF\_INQ\_DIM returns
190 the dimension name and length.
191 
192 Variable IDs are also assigned from consecutive integers 1, 2, 3, ... up
193 to the number of variables. These can be used in NF\_INQ\_VAR calls to
194 find out the names, types, shapes, and the number of attributes assigned
195 to each variable.
196 
197 Once the number of attributes for a variable is known,ccessive calls
198 to NF\_INQ\_ATTNAME return the name for each attribute given the netCDF
199 ID, variable ID, and attribute number. Armed with the attribute name, a
200 call to NF\_INQ\_ATT returns its type and length. Given the type and
201 length, you can allocate enough space to hold the attribute values. Then
202 a call to a member of the NF\_GET\_ATT family returns the attribute
203 values.
204 
205 Once the IDs and shapes of netCDF variables are known, data values can
206 be accessed by calling a member of the NF\_GET\_VAR1 family for single
207 values, or members of the NF\_GET\_VAR, NF\_GET\_VARA, NF\_GET\_VARS, or
208 NF\_GET\_VARM for various kinds of array access.
209 
210 1.4 Adding New Dimensions, Variables, Attributes {#Adding_New_Dimensions__Variables__Attributes}
211 ------------------------------------------------
212 
213 An existing netCDF dataset can be extensively altered. New dimensions,
214 variables, and attributes can be added or existing ones renamed, and
215 existing attributes can be deleted. Existing dimensions, variables, and
216 attributes can be renamed. The following code template lists a typical
217 sequence of calls to add new netCDF components to an existing dataset:
218 
219  
220 
221 
222  NF_OPEN ! open existing netCDF dataset
223  ...
224  NF_REDEF ! put it into define mode
225  ...
226  NF_DEF_DIM ! define additional dimensions (if any)
227  ...
228  NF_DEF_VAR ! define additional variables (if any)
229  ...
230  NF_PUT_ATT ! define other attributes (if any)
231  ...
232  NF_ENDDEF ! check definitions, leave define mode
233  ...
234  NF_PUT_VAR ! provide new variable values
235  ...
236  NF_CLOSE ! close netCDF dataset
237 
238 
239 A netCDF dataset is first opened by the NF\_OPEN call. This call puts
240 the open dataset in data mode, which means existing data values can be
241 accessed and changed, existing attributes can be changed (so long as
242 they do not grow), but nothing can be added. To add new netCDF
243 dimensions, variables, or attributes you must enter define mode, by
244 calling NF\_REDEF.In define mode, call NF\_DEF\_DIM to define new
245 dimensions, NF\_DEF\_VAR to define new variables, and a member of the
246 NF\_PUT\_ATT family to assign new attributes to variables or enlarge old
247 attributes.
248 
249 You can leave define mode and reenter data mode, checking all the new
250 definitions for consistency and committing the changes to disk, by
251 calling NF\_ENDDEF. If you do not wish to reenter data mode, just call
252 NF\_CLOSE, which will have the effect of first calling NF\_ENDDEF.
253 
254 Until the NF\_ENDDEF call, you may back out of all the redefinitions
255 made in define mode and restore the previous state of the netCDF dataset
256 by calling NF\_ABORT. You may also use the NF\_ABORT call to restore the
257 netCDF dataset to a consistent state if the call to NF\_ENDDEF fails. If
258 you have called NF\_CLOSE from definition mode and the implied call to
259 NF\_ENDDEF fails, NF\_ABORT will automatically be called to close the
260 netCDF dataset and leave it in its previous consistent state (before you
261 entered define mode).
262 
263 At most one process should have a netCDF dataset open for writing at one
264 time. The library is designed to provide limitedpport for multiple
265 concurrent readers with one writer, via disciplined use of the NF\_SYNC
266 function and the NF\_SHARE flag. If a writer makes changes in define
267 mode,ch as the addition of new variables, dimensions, or attributes,
268 some means external to the library is necessary to prevent readers from
269 making concurrent accesses and to inform readers to call NF\_SYNC before
270 the next access.
271 
272 1.5 Error Handling {#Error_Handling_1_5}
273 ------------------
274 
275 The netCDF library provides the facilities needed to handle errors in a
276 flexible way. Each netCDF function returns an integer status value. If
277 the returned status value indicates an error, you may handle it in any
278 way desired, from printing an associated error message and exiting to
279 ignoring the error indication and proceeding (not recommended!). For
280 simplicity, the examples in this guide check the error status and call a
281 separate function to handle any errors.
282 
283 The NF\_STRERROR function is available to convert a returned integer
284 error status into an error message string.
285 
286 Occasionally, low-level I/O errors may occur in a layer below the netCDF
287 library. For example, if a write operation causes you to exceed disk
288 quotas or to attempt to write to a device that is no longer available,
289 you may get an error from a layer below the netCDF library, but the
290 rlting write error will still be reflected in the returned status
291 value.
292 
293 1.6 Compiling and Linking with the NetCDF Library {#Compiling_and_Linking_with_the_NetCDF_Library}
294 -------------------------------------------------
295 
296 Details of how to compile and link a program that uses the netCDF C or
297 FORTRAN interfaces differ, depending on the operating system, the
298 available compilers, and where the netCDF library and include files are
299 installed. Nevertheless, we provide here examples of how to compile and
300 link a program that uses the netCDF library on a Unix platform, so that
301 you can adjust these examples to fit your installation.
302 
303 Every FORTRAN file that references netCDF functions or constants must
304 contain an appropriate INCLUDE statement before the first
305 reference:
306 
307  INCLUDE 'netcdf.inc'
308 
309 
310 Unless the netcdf.inc file is installed in a standard directory where
311 the FORTRAN compiler always looks, you must use the -I option when
312 invoking the compiler, to specify a directory where netcdf.inc is
313 installed, for example:
314 
315  f77 -c -I/usr/local/include myprogram.f
316 
317 
318 Unless the netCDF library is installed in a standard directory where the
319 linker always looks, you must use the -L and -l options to link an
320 object file that uses the netCDF library. Since version 4.1.3, the
321 netCDF Fortran library (named ‘libnetcdff’) is distinct from the netCDF
322 C library (named ‘libnetcdf’), but depends on it. If it is installed as
323 a shared library, you need only use ‘-lnetcdff’ to specify the Fortran
324 library for linking.
325 
326 For example, if installed as a shared library, use something like:
327 
328 
329  f77 -o myprogram myprogram.o -L/usr/local/lib -lnetcdff
330 
331 
332 If installed as a static library, you will at least need to mention the
333 netCDF C library and perhaps other libraries,ch as hdf5 or curl,
334 depending on how the C library was built. For example:
335 
336  
337 
338 
339  f77 -o myprogram myprogram.o -L/usr/local/lib -lnetcdff -lnetcdf
340 
341 
342 Use of the nf-config utility program, installed as part of the
343 netcdf-fortran software, provides an easier way to compile and link,
344 without needing to know the details of where the library has been
345 installed, or whether it is installed as a shared or static library.
346 
347 To see all the options for ‘nf-config’, invoke it with the ‘–help’
348 argument.
349 
350 Here’s an example of how you could use ‘nf-config’ to compile and link a
351 Fortran program in one step:
352 
353  
354 
355 
356  f77 myprogram.f -o myprogram `nf-config --fflags --flibs`
357 
358 
359 If it is installed on your system, you could also use the ‘pkg-config’
360 utility to compile and link Fortran programs with the netCDF libraries.
361 This is especially useful in Makefiles, to ilate them from changes to
362 library versions and dependencies. Here is an example of how you could
363 compile and link a Fortran program with netCDF libraries using
364 pkg-config:
365 
366  
367 
368 
369  export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
370  f77 myprogram.f -o myprogram `pkg-config --cflags --libs netcdf-fortran`
371 
372 
373 where here ‘–cflags’ means compiler flags and ‘libs’ requests that the
374 approriate libraries be linked in.
375 
376 
377 
378 2. Datasets {#Datasets_}
379 ===========
380 
381 2.1 Datasets Introduction {#Datasets_Introduction}
382 -------------------------
383 
384 This presents the interfaces of the netCDF functions that deal
385 with a netCDF dataset or the whole netCDF library.
386 
387 A netCDF dataset that has not yet been opened can only be referred to by
388 its dataset name. Once a netCDF dataset is opened, it is referred to by
389 a netCDF ID, which is a small nonnegative integer returned when you
390 create or open the dataset. A netCDF ID is much like a file descriptor
391 in C or a logical unit number in FORTRAN. In any single program, the
392 netCDF IDs of distinct open netCDF datasets are distinct. A single
393 netCDF dataset may be opened multiple times and will then have multiple
394 distinct netCDF IDs; however at most one of the open instances of a
395 single netCDF dataset should permit writing. When an open netCDF dataset
396 is closed, the ID is no longer associated with a netCDF dataset.
397 
398 Functions that deal with the netCDF library include:
399 
400 - Get version of library.
401 - Get error message corresponding to a returned error code.
402 
403 The operationspported on a netCDF dataset as a single object are:
404 
405 - Create, given dataset name and whether to overwrite or not.
406 - Open for access, given dataset name and read or write intent.
407 - Put into define mode, to add dimensions, variables, or attributes.
408 - Take out of define mode, checking consistency of additions.
409 - Close, writing to disk if required.
410 - Inquire about the number of dimensions, number of variables, number
411  of global attributes, and ID of the unlimited dimension, if any.
412 - Synchronize to disk to makere it is current.
413 - Set and unset nofill mode for optimized sequential writes.
414 - After ammary of conventions used in describing the netCDF
415  interfaces, the rest of this presents a detailed description
416  of the interfaces for these operations.
417 
418 2.2 NetCDF Library Interface Descriptions {#NetCDF_Library_Interface_Descriptions}
419 -----------------------------------------
420 
421 Each interface description for a particular netCDF function in this and
422 laters contains:
423 
424 - a description of the purpose of the function;
425 - a FORTRAN function prototype that presents the type and order of the
426  formal parameters to the function;
427 - a description of each formal parameter in the C interface;
428 - a list of possible error conditions; and
429 - an example of a FORTRAN program fragment calling the netCDF function
430  (and perhaps other netCDF functions).
431 
432 The examples follow a simple convention for error handling, always
433 checking the error status returned from each netCDF function call and
434 calling a handle\_error function in case an error was detected. For an
435 example ofch a function, see Section 5.2 "Get error message
436 corresponding to error status: nf\_strerror".
437 
438 2.3 NF_STRERROR {#NF_STRERROR}
439 ----------------
440 
441 The function NF\_STRERROR returns a static reference to an error message
442 string corresponding to an integer netCDF error status or to a system
443 error number, prmably returned by a previous call to some other
444 netCDF function. The list of netCDF error status codes is available in
445 the appropriate include file for each language binding.
446 
447 ### Usage
448 
449 ~~~
450 CHARACTER*80 FUNCTION NF_STRERROR(INTEGER NCERR)
451 ~~~
452 
453  `NCERR`
454 : An error status that might have been returned from a previous call
455  to some netCDF function.
456 
457 
458 ### Errors
459 
460 If you provide an invalid integer error status that does not correspond
461 to any netCDF error message or or to any system error message (as
462 understood by the system strerror function), NF\_STRERROR returns a
463 string indicating that there is noch error status.
464 
465 ### Example
466 
467 Here is an example of a simple error handling function that uses
468 NF\_STRERROR to print the error message corresponding to the netCDF
469 error status returned from any netCDF function call and then exit:
470 
471  
472 
473 ~~~
474 INCLUDE 'netcdf.inc'
475  ...
476 SUBROUTINE HANDLE_ERR(STATUS)
477 INTEGER STATUS
478 IF (STATUS .NE. NF_NOERR) THEN
479  PRINT *, NF_STRERROR(STATUS)
480  STOP 'Stopped'
481 ENDIF
482 END
483 ~~~
484 
485 
486 2.4 Get netCDF library version: NF_INQ_LIBVERS {#Get_netCDF_library_version_NF_INQ_LIBVERS}
487 ------------------------------------------------
488 
489 The function NF\_INQ\_LIBVERS returns a string identifying the version
490 of the netCDF library, and when it was built.
491 
492 ### Usage
493 
494 ~~~
495 CHARACTER*80 FUNCTION NF_INQ_LIBVERS()
496 ~~~
497 
498 ### Errors
499 
500 This function takes no arguments, and thus no errors are possible in its
501 invocation.
502 
503 ### Example
504 
505 Here is an example using nf\_inq\_libvers to print the version of the
506 netCDF library with which the program is linked:
507 
508 
509 ~~~
510 INCLUDE 'netcdf.inc'
511  ...
512 PRINT *, NF_INQ_LIBVERS()
513 ~~~
514 
515 2.5 NF_CREATE {#NF_CREATE}
516 --------------
517 
518 This function creates a new netCDF dataset, returning a netCDF ID that
519 can sequently be used to refer to the netCDF dataset in other netCDF
520 function calls. The new netCDF dataset opened for write access and
521 placed in define mode, ready for you to add dimensions, variables, and
522 attributes.
523 
524 A creation mode flag specifies whether to overwrite any existing dataset
525 with the same name and whether access to the dataset is shared.
526 
527 ### Usage
528  
529 ~~~
530 INTEGER FUNCTION NF_CREATE (CHARACTER*(*) PATH, INTEGER CMODE,
531  INTEGER ncid)
532 ~~~
533 
534  `PATH`: The file name of the new netCDF dataset.
535 
536  `CMODE`: The creation mode flag. The following flags are available:
537  NF\_NOCLOBBER, NF\_SHARE, NF\_64BIT\_OFFSET, NF\_NETCDF4 and
538  NF\_CLASSIC\_MODEL. You can combine the affect of multiple flags in
539  a single argument by using the bitwise OR operator. For example, to
540  specify both NF\_NOCLOBBER and NF\_SHARE, you could provide the
541  argument OR(NF\_NOCLOBBER, NF\_SHARE).
542 
543 
544 A zero value (defined for convenience as NF_CLOBBER) specifies the
545 default behavior: overwrite any existing dataset with the same file
546 name and buffer and cache accesses for efficiency. The dataset will
547 be in netCDF classic format. See 'NetCDF Classic Format Limitations'
548 in The NetCDF Users Guide.
549 
550 Setting NF\_NOCLOBBER means you do not want to clobber (overwrite)
551 an existing dataset; an error (NF_EEXIST) is returned if the
552 specified dataset already exists.
553 
554 The NF\_SHARE flag is appropriate when one process may be writing
555 the dataset and one or more other processes reading the dataset
556 concurrently; it means that dataset accesses are not buffered and
557 caching is limited. Since the buffering scheme is optimized for
558 sequential access, programs that do not access data sequentially may
559 see some performance improvement by setting the NF\_SHARE flag. This
560 only applied to classic and 64-bit offset format files.
561 
562 Setting NF\_64BIT\_OFFSET causes netCDF to create a 64-bit offset
563 format file, instead of a netCDF classic format file. The 64-bit
564 offset format imposes far fewer restrictions on very large (i.e.
565 over 2 GB) data files. See [(netcdf)Large File
566 Support](netcdf.html#Large-File-Support) ‘Large File
567 Support’ in The NetCDF Users Guide.
568 
569 Setting NF\_NETCDF4 causes netCDF to create a netCDF-4/HDF5 format
570 file. Oring NF\_CLASSIC\_MODEL with NF\_NETCDF4 causes the netCDF
571 library to create a netCDF-4/HDF5 data file, with the netCDF classic
572 model enforced - none of the new features of the netCDF-4 data model
573 may be usedinch a file, for example groups and user-defined
574 types.
575 
576  `ncid`
577 : Returned netCDF ID.
578 
579 ### Errors
580 
581 NF\_CREATE returns the value NF\_NOERR if no errors occurred. Possible
582 causes of errors include:
583 
584 - Passing a dataset name that includes a directory that does not
585  exist.
586 - Specifying a dataset name of a file that exists and also specifying
587  NF\_NOCLOBBER.
588 - Specifying a meaningless value for the creation mode.
589 - Attempting to create a netCDF dataset in a directory where you don’t
590  have permission to create files.
591 
592 ### Example
593 
594 In this example we create a netCDF dataset named foo.nc; we want the
595 dataset to be created in the current directory only if a dataset with
596 that name does not already exist:
597 
598  
599 
600 ~~~
601 INCLUDE 'netcdf.inc'
602  ...
603 INTEGER NCID, STATUS
604 ...
605 STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
606 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
607 ~~~
608 
609 2.6 NF__CREATE {#NF__CREATE}
610 ----------------
611 
612 This function is a variant of NF\_CREATE, NF\_\_CREATE (note the double
613 underscore) allows users to specify two tuning parameters for the file
614 that it is creating. These tuning parameters are not written to the data
615 file, they are only used for so long as the file remains open after an
616 NF\_\_CREATE.
617 
618 This function creates a new netCDF dataset, returning a netCDF ID that
619 canbsequently be used to refer to the netCDF dataset in other netCDF
620 function calls. The new netCDF dataset opened for write access and
621 placed in define mode, ready for you to add dimensions, variables, and
622 attributes.
623 
624 A creation mode flag specifies whether to overwrite any existing dataset
625 with the same name and whether access to the dataset is shared.
626 
627 ### Usage
628 
629 ~~~
630 INTEGER FUNCTION NF__CREATE (CHARACTER*(*) PATH, INTEGER CMODE, INTEGER INITIALSZ,
631  INTEGER BUFRSIZEHINT, INTEGER ncid)
632 
633 ~~~
634  `PATH`
635 : The file name of the new netCDF dataset.
636 
637  `CMODE`
638 : The creation mode flag. The following flags are available:
639  NF\_NOCLOBBER, NF\_SHARE, NF\_64BIT\_OFFSET, NF\_NETCDF4, and
640  NF\_CLASSIC\_MODEL.
641 
642  Setting NF\_NOCLOBBER means you do not want to clobber (overwrite)
643  an existing dataset; an error (NF\_EEXIST) is returned if the
644  specified dataset already exists.
645 
646  The NF\_SHARE flag is appropriate when one process may be writing
647  the dataset and one or more other processes reading the dataset
648  concurrently; it means that dataset accesses are not buffered and
649  caching is limited. Since the buffering scheme is optimized for
650  sequential access, programs that do not access data sequentially may
651  see some performance improvement by setting the NF\_SHARE flag. This
652  flag has no effect with netCDF-4/HDF5 files.
653 
654  Setting NF\_64BIT\_OFFSET causes netCDF to create a 64-bit offset
655  format file, instead of a netCDF classic format file. The 64-bit
656  offset format imposes far fewer restrictions on very large (i.e.
657  over 2 GB) data files. See [(netcdf)Large File
658  Support](netcdf.html#Large-File-Support) ‘Large File
659  Support’ in The NetCDF Users Guide.
660 
661  Setting NF\_CLASSIC\_MODEL causes netCDF to enforce the classic data
662  model in this file. (This only has effect for netCDF-4/HDF5 files,
663  as classic and 64-bit offset files always use the classic model.)
664  When used with NF\_NETCDF4, this flag eres that the rlting
665  netCDF-4/HDF5 file may never contain any new constructs from the
666  enhanced data model. That is, it cannot contain groups, user defined
667  types, multiple unlimited dimensions, or new atomic types. The
668  advantage of this restriction is thatch files are guarenteed to
669  work with existing netCDF software.
670 
671  A zero value (defined for convenience as NF\_CLOBBER) specifies the
672  default behavior: overwrite any existing dataset with the same file
673  name and buffer and cache accesses for efficiency. The dataset will
674  be in netCDF classic format. See [(netcdf)NetCDF Classic Format
675  Limitations](netcdf.html#NetCDF-Classic-Format-Limitations)
676  ‘NetCDF Classic Format Limitations’ in The NetCDF Users Guide.
677 
678  `INITIALSZ`
679 : This parameter sets the initial size of the file at creation time.
680 
681  `BUFRSIZEHINT`
682 : The argument referenced by BUFRSIZEHINT controls a space ves time
683  tradeoff, memory allocated in the netcdf library ves number of
684  system calls.
685 
686  Because of internal requirements, the value may not be set to
687  exactly the value requested. The actual value chosen is returned by
688  reference.
689 
690  Using the value NF\_SIZEHINT\_DEFAULT causes the library to choose a
691  default. How the system chooses the default depends on the system.
692  On many systems, the "preferred I/O block size" is available from
693  the stat() system call, struct stat member st\_blksize. If this is
694  available it is used. Lacking that, twice the system pagesize is
695  used.
696 
697  Lacking a call to discover the system pagesize, we just set default
698  bufrsize to 8192.
699 
700  The BUFRSIZE is a property of a given open netcdf descriptor ncid,
701  it is not a persistent property of the netcdf dataset.
702 
703  `ncid`
704 : Returned netCDF ID.
705 
706 ### Errors
707 
708 NF\_\_CREATE returns the value NF\_NOERR if no errors occurred. Possible
709 causes of errors include:
710 
711 - Passing a dataset name that includes a directory that does not
712  exist.
713 - Specifying a dataset name of a file that exists and also specifying
714  NF\_NOCLOBBER.
715 - Specifying a meaningless value for the creation mode.
716 - Attempting to create a netCDF dataset in a directory where you don’t
717  have permission to create files.
718 
719 ### Example
720 
721 In this example we create a netCDF dataset named foo.nc; we want the
722 dataset to be created in the current directory only if a dataset with
723 that name does not already exist:
724 
725  
726 
727 ~~~
728 INCLUDE 'netcdf.inc'
729  ...
730 INTEGER NCID, STATUS, INITIALSZ, BUFRSIZEHINT
731 ...
732 INITIALSZ = 2048
733 BUFRSIZEHINT = 1024
734 STATUS = NF__CREATE('foo.nc', NF_NOCLOBBER, INITIALSZ, BUFRSIZEHINT, NCID)
735 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
736 ~~~
737 
738 2.7 NF_CREATE_PAR {#NF_CREATE_PAR}
739 -------------------
740 
741 This function is a variant of nf\_create, nf\_create\_par allows users
742 to open a file on a MPI/IO or MPI/Posix parallel file system.
743 
744 The parallel parameters are not written to the data file, they are only
745 used for so long as the file remains open after an nf\_create\_par.
746 
747 This function is only available if the netCDF library was built with
748 parallel I/O.
749 
750 This function creates a new netCDF dataset, returning a netCDF ID that
751 canbsequently be used to refer to the netCDF dataset in other netCDF
752 function calls. The new netCDF dataset opened for write access and
753 placed in define mode, ready for you to add dimensions, variables, and
754 attributes.
755 
756 When a netCDF-4 file is created for parallel access, independent
757 operations are the default. To use collective access on a variable, See
758 section [Change between Collective and Independent Parallel Access:
759 NF\_VAR\_PAR\_ACCESS](#NF_005fVAR_005fPAR_005fACCESS).
760 
761 ### Usage
762 
763 ~~~
764 INTEGER FUNCTION NF_CREATE_PAR(CHARACTER*(*) PATH, INTEGER CMODE,
765  INTEGER MPI_COMM, INTEGER MPI_INFO,
766  INTEGER ncid)
767 ~~~
768 
769  `PATH`
770 : The file name of the new netCDF dataset.
771 
772  `CMODE`
773 : The creation mode flag. The following flags are available:
774  NF\_NOCLOBBER, NF\_NETCDF4 and NF\_CLASSIC\_MODEL. You can combine
775  the affect of multiple flags in a single argument by using the
776  bitwise OR operator. For example, to specify both NF\_NOCLOBBER and
777  NF\_NETCDF4, you could provide the argument OR(NF\_NOCLOBBER,
778  NF\_NETCDF4).
779 
780  Setting NF\_NETCDF4 causes netCDF to create a netCDF-4/HDF5 format
781  file. Oring NF\_CLASSIC\_MODEL with NF\_NETCDF4 causes the netCDF
782  library to create a netCDF-4/HDF5 data file, with the netCDF classic
783  model enforced - none of the new features of the netCDF-4 data model
784  may be usedinch a file, for example groups and user-defined
785  types.
786 
787  Only netCDF-4/HDF5 files may be used with parallel I/O.
788 
789  `MPI_COMM`
790 : The MPI communicator.
791 
792  `MPI_INFO`
793 : The MPI info.
794 
795  `ncid`
796 : Returned netCDF ID.
797 
798 ### Errors
799 
800 
801 NF\_CREATE returns the value NF\_NOERR if no errors occurred. Possible
802 causes of errors include:
803 
804 - Passing a dataset name that includes a directory that does not
805  exist.
806 - Specifying a dataset name of a file that exists and also specifying
807  NF\_NOCLOBBER.
808 - Specifying a meaningless value for the creation mode.
809 - Attempting to create a netCDF dataset in a directory where you don’t
810  have permission to create files.
811 
812 ### Example
813 
814 
815 This example is from test program nf\_test/ftst\_parallel.F.
816 
817  
818 
819 ~~~
820 ! Create the netCDF file.
821  mode_flag = IOR(nf_netcdf4, nf_classic_model)
822  retval = nf_create_par(FILE_NAME, mode_flag, MPI_COMM_WORLD,
823  $ MPI_INFO_NULL, ncid)
824  if (retval .ne. nf_noerr) stop 2
825 ~~~
826 
827 
828 2.8 NF_OPEN {#NF_OPEN_}
829 ------------
830 
831 The function NF\_OPEN opens an existing netCDF dataset for access.
832 
833 ### Usage
834 
835 ~~~
836 INTEGER FUNCTION NF_OPEN(CHARACTER*(*) PATH, INTEGER OMODE, INTEGER ncid)
837 ~~~
838 
839  `PATH`
840 : File name for netCDF dataset to be opened. This may be an OPeNDAP
841  URL if DAPpport is enabled.
842 
843  `OMODE`
844 : A zero value (or NF\_NOWRITE) specifies: open the dataset with
845  read-only access, buffering and caching accesses for efficiency.
846 
847  Otherwise, the creation mode is NF\_WRITE, NF\_SHARE, or
848  OR(NF\_WRITE, NF\_SHARE). Setting the NF\_WRITE flag opens the
849  dataset with read-write access. ("Writing" means any kind of change
850  to the dataset, including appending or changing data, adding or
851  renaming dimensions, variables, and attributes, or deleting
852  attributes.) The NF\_SHARE flag is appropriate when one process may
853  be writing the dataset and one or more other processes reading the
854  dataset concurrently; it means that dataset accesses are not
855  buffered and caching is limited. Since the buffering scheme is
856  optimized for sequential access, programs that do not access data
857  sequentially may see some performance improvement by setting the
858  NF\_SHARE flag.
859 
860  `ncid`
861 : Returned netCDF ID.
862 
863 ### Errors
864 
865 
866 NF\_OPEN returns the value NF\_NOERR if no errors occurred. Otherwise,
867 the returned status indicates an error. Possible causes of errors
868 include:
869 
870 - The specified netCDF dataset does not exist.
871 - A meaningless mode was specified.
872 
873 ### Example
874 
875 Here is an example using NF\_OPEN to open an existing netCDF dataset
876 named foo.nc for read-only, non-shared access:
877 
878 ~~~
879 INCLUDE 'netcdf.inc'
880  ...
881 INTEGER NCID, STATUS
882 ...
883 STATUS = NF_OPEN('foo.nc', 0, NCID)
884 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
885 ~~~
886 
887 2.9 NF__OPEN {#NF__OPEN_}
888 --------------
889 
890 The function NF\_OPEN opens an existing netCDF dataset for access, with
891 a performance tuning parameter.
892 
893 ### Usage
894 
895 ~~~
896 INTEGER FUNCTION NF_OPEN(CHARACTER*(*) PATH, INTEGER OMODE, INTEGER
897 BUFRSIZEHINT, INTEGER ncid)
898 ~~~
899 
900  `PATH`
901 : File name for netCDF dataset to be opened.
902 
903  `OMODE`
904 : A zero value (or NF\_NOWRITE) specifies: open the dataset with
905  read-only access, buffering and caching accesses for efficiency
906 
907  Otherwise, the creation mode is NF\_WRITE, NF\_SHARE, or
908  OR(NF\_WRITE,NF\_SHARE). Setting the NF\_WRITE flag opens the
909  dataset with read-write access. ("Writing" means any kind of change
910  to the dataset, including appending or changing data, adding or
911  renaming dimensions, variables, and attributes, or deleting
912  attributes.) The NF\_SHARE flag is appropriate when one process may
913  be writing the dataset and one or more other processes reading the
914  dataset concurrently; it means that dataset accesses are not
915  buffered and caching is limited. Since the buffering scheme is
916  optimized for sequential access, programs that do not access data
917  sequentially may see some performance improvement by setting the
918  NF\_SHARE flag.
919 
920  `BUFRSIZEHINT`
921 : This argument controls a space ves time tradeoff, memory
922  allocated in the netcdf library ves number of system calls.
923 
924  Because of internal requirements, the value may not be set to
925  exactly the value requested. The actual value chosen is returned by
926  reference.
927 
928  Using the value NF\_SIZEHINT\_DEFAULT causes the library to choose a
929  default. How the system chooses the default depends on the system.
930  On many systems, the "preferred I/O block size" is available from
931  the stat() system call, struct stat member st\_blksize. If this is
932  available it is used. Lacking that, twice the system pagesize is
933  used.
934 
935  Lacking a call to discover the system pagesize, we just set default
936  bufrsize to 8192.
937 
938  The bufrsize is a property of a given open netcdf descriptor ncid,
939  it is not a persistent property of the netcdf dataset.
940 
941  `ncid`
942 : Returned netCDF ID.
943 
944 ### Errors
945 
946 
947 NF\_\_OPEN returns the value NF\_NOERR if no errors occurred. Otherwise,
948 the returned status indicates an error. Possible causes of errors
949 include:
950 
951 - The specified netCDF dataset does not exist.
952 - A meaningless mode was specified.
953 
954 ### Example
955 
956 Here is an example using NF\_\_OPEN to open an existing netCDF dataset
957 named foo.nc for read-only, non-shared access:
958 
959 
960 ~~~
961 INCLUDE 'netcdf.inc'
962  ...
963 INTEGER NCID, STATUS, BUFRSIZEHINT
964 ...
965 BUFRSIZEHINT = 1024
966 STATUS = NF_OPEN('foo.nc', 0, BUFRSIZEHINT, NCID)
967 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
968 ~~~
969 
970 2.10 NF\_OPEN\_PAR {#NF_OPEN_PAR}
971 ------------------
972 
973 This function opens a netCDF-4 dataset for parallel access.
974 
975 This function is only available if the netCDF library was built with a
976 HDF5 library for which –enable-parallel was used, and which was linked
977 (like HDF5) to MPI libraries.
978 
979 This opens the file using either MPI-IO or MPI-POSIX. The file must be a
980 netCDF-4 file. (That is, it must have been created using NF\_NETCDF4 in
981 the creation mode).
982 
983 This function is only available if netCDF-4 was build with a version of
984 the HDF5 library which was built with –enable-parallel.
985 
986 Before either HDF5 or netCDF-4 can be installed withpport for
987 parallel programming, and MPI layer must also be installed on the
988 machine, and ally a parallel file system.
989 
990 NetCDF-4 exposes the parallel access functionality of HDF5. For more
991 information about what is required to install and use the parallel
992 access functions, see the HDF5 web site.
993 
994 When a netCDF-4 file is opened for parallel access, collective
995 operations are the default. To use independent access on a variable, See
996 section [Change between Collective and Independent Parallel Access:
997 NF\_VAR\_PAR\_ACCESS](#NF_005fVAR_005fPAR_005fACCESS).
998 
999 Usage
1000 -----
1001 
1002 ~~~
1003 INTEGER FUNCTION NF_OPEN_PAR(CHARACTER*(*) PATH, INTEGER OMODE,
1004  INTEGER MPI_COMM, INTEGER MPI_INFO,
1005  INTEGER ncid)
1006 ~~~
1007 
1008  `PATH`
1009 : File name for netCDF dataset to be opened.
1010 
1011  `OMODE`
1012 : A zero value (or NF\_NOWRITE) specifies: open the dataset with
1013  read-only access.
1014 
1015  Otherwise, the mode may be NF\_WRITE. Setting the NF\_WRITE flag
1016  opens the dataset with read-write access. ("Writing" means any kind
1017  of change to the dataset, including appending or changing data,
1018  adding or renaming dimensions, variables, and attributes, or
1019  deleting attributes.)
1020 
1021  Setting NF\_NETCDF4 is not necessary (or allowed). The file type is
1022  detected automatically.
1023 
1024  `MPI_COMM`
1025 : The MPI communicator.
1026 
1027  `MPI_INFO`
1028 : The MPI info.
1029 
1030  `ncid`
1031 : Returned netCDF ID.
1032 
1033 Errors
1034 ------
1035 
1036 NF\_OPEN returns the value NF\_NOERR if no errors occurred. Otherwise,
1037 the returned status indicates an error. Possible causes of errors
1038 include:
1039 
1040 - The specified netCDF dataset does not exist.
1041 - A meaningless mode was specified.
1042 - Not a netCDF-4 file.
1043 
1044 Example
1045 -------
1046 
1047 This example is from the test program nf\_test/ftst\_parallel.F.
1048 
1049  
1050 
1051 
1052 ! Reopen the file.
1053  retval = nf_open_par(FILE_NAME, nf_nowrite, MPI_COMM_WORLD,
1054  $ MPI_INFO_NULL, ncid)
1055  if (retval .ne. nf_noerr) stop 2
1056 
1057 
1058 2.11 NF\_REDEF
1059 --------------
1060 
1061 The function NF\_REDEF puts an open netCDF dataset into define mode, so
1062 dimensions, variables, and attributes can be added or renamed and
1063 attributes can be deleted.
1064 
1065 Usage
1066 -----
1067 
1068  
1069 
1070 
1071 INTEGER FUNCTION NF_REDEF(INTEGER NCID)
1072 
1073 
1074  `NCID`
1075 : netCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1076 
1077 Errors
1078 ------
1079 
1080 NF\_REDEF returns the value NF\_NOERR if no errors occurred. Otherwise,
1081 the returned status indicates an error. Possible causes of errors
1082 include:
1083 
1084 - The specified netCDF dataset is already in define mode.
1085 - The specified netCDF dataset was opened for read-only.
1086 - The specified netCDF ID does not refer to an open netCDF dataset.
1087 
1088 Example
1089 -------
1090 
1091 Here is an example using NF\_REDEF to open an existing netCDF dataset
1092 named foo.nc and put it into define mode:
1093 
1094  
1095 
1096 
1097 INCLUDE 'netcdf.inc'
1098  ...
1099 INTEGER NCID, STATUS
1100  ...
1101 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID) ! open dataset
1102 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1103  ...
1104 STATUS = NF_REDEF(NCID) ! put in define mode
1105 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1106 
1107 
1108 2.12 NF\_ENDDEF
1109 ---------------
1110 
1111 The function NF\_ENDDEF takes an open netCDF dataset out of define mode.
1112 The changes made to the netCDF dataset while it was in define mode are
1113 checked and committed to disk if no problems occurred. Non-record
1114 variables may be initialized to a "fill value" as well (see
1115 [NF\_SET\_FILL](#NF_005fSET_005fFILL)). The netCDF dataset is then
1116 placed in data mode, so variable data can be read or written.
1117 
1118 This call may involve copying data under some circumstances. See
1119 [(netcdf)File Structure and
1120 Performance](netcdf.html#File-Structure-and-Performance) ‘File
1121 Structure and Performance’ in NetCDF Users’ Guide.
1122 
1123 Usage
1124 -----
1125 
1126  
1127 
1128 
1129 INTEGER FUNCTION NF_ENDDEF(INTEGER NCID)
1130 
1131 
1132  `NCID`
1133 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1134 
1135 Errors
1136 ------
1137 
1138 NF\_ENDDEF returns the value NF\_NOERR if no errors occurred. Otherwise,
1139 the returned status indicates an error. Possible causes of errors
1140 include:
1141 
1142 - The specified netCDF dataset is not in define mode.
1143 - The specified netCDF ID does not refer to an open netCDF dataset.
1144  The size of one or more variables exceed the size constraints for
1145  whichever variant of the file format is in use). See [(netcdf)Large
1146  File Support](netcdf.html#Large-File-Support) ‘Large File
1147  Support’ in The NetCDF Users Guide.
1148 
1149 Example
1150 -------
1151 
1152 Here is an example using NF\_ENDDEF to finish the definitions of a new
1153 netCDF dataset named foo.nc and put it into data mode:
1154 
1155  
1156 
1157 
1158 INCLUDE 'netcdf.inc'
1159  ...
1160 INTEGER NCID, STATUS
1161  ...
1162 STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
1163 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1164 
1165  ... ! create dimensions, variables, attributes
1166 
1167 STATUS = NF_ENDDEF(NCID)
1168 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1169 
1170 
1171 2.13 NF\_\_ENDDEF
1172 -----------------
1173 
1174 The function NF\_\_ENDDEF takes an open netCDF dataset out of define
1175 mode. The changes made to the netCDF dataset while it was in define mode
1176 are checked and committed to disk if no problems occurred. Non-record
1177 variables may be initialized to a "fill value" as well (see
1178 [NF\_SET\_FILL](#NF_005fSET_005fFILL)). The netCDF dataset is then
1179 placed in data mode, so variable data can be read or written.
1180 
1181 This call may involve copying data under some circumstances. See
1182 [(netcdf)File Structure and
1183 Performance](netcdf.html#File-Structure-and-Performance) ‘File
1184 Structure and Performance’ in NetCDF Users’ Guide.
1185 
1186 This function ames specific characteristics of the netcdf version 1
1187 and version 2 file formats. Users should use nf\_enddef in most
1188 circumstances. Although this function will be available in future netCDF
1189 implementations, it may not continue to have any effect on performance.
1190 
1191 The current netcdf file format has threes, the "header",
1192 the data for fixed size variables, and the data for
1193 variables which have an unlimited dimension (record variables).
1194 
1195 The header begins at the beginning of the file. The index (offset) of
1196 the beginning of the other twos is contained in the header.
1197 Typically, there is no space between thes. This causes copying
1198 overhead to accrue if one wishes to change the size of thes, as
1199 may happen when changing names of things, text attribute values, adding
1200 attributes or adding variables. Also, for buffered i/o, there may be
1201 advantages to alignings in certain ways.
1202 
1203 The minfree parameters allow one to control costs of future calls to
1204 nf\_redef, nf\_enddef by requesting that minfree bytes be available at
1205 the end of the.
1206 
1207 The align parameters allow one to set the alignment of the beginning of
1208 the correspondings. The beginning of the is rounded up
1209 to an index which is a multiple of the align parameter. The flag value
1210 ALIGN\_CHUNK tells the library to use the bufrsize (see above) as the
1211 align parameter.
1212 
1213 The file format requires mod 4 alignment, so the align parameters are
1214 silently rounded up to multiples of 4. The al call,
1215 
1216  
1217 
1218 
1219 nf_enddef(ncid);
1220 
1221 
1222 is equivalent to
1223 
1224 
1225 nf_enddef(ncid, 0, 4, 0, 4);
1226 
1227 
1228 The file format does not contain a "record size" value, this is
1229 calculated from the sizes of the record variables. This unfortunate fact
1230 prevents us from providing minfree and alignment control of the
1231 "records" in a netcdf file. If you add a variable which has an unlimited
1232 dimension, the third will always be copied with the new variable
1233 added.
1234 
1235 Usage
1236 -----
1237 
1238  
1239 
1240 
1241 INTEGER FUNCTION NF_ENDDEF(INTEGER NCID, INTEGER H_MINFREE, INTEGER V_ALIGN,
1242  INTEGER V_MINFREE, INTEGER R_ALIGN)
1243 
1244 
1245  `NCID`
1246 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1247 
1248  `H_MINFREE`
1249 : Sets the pad at the end of the "header".
1250 
1251  `V_ALIGN`
1252 : Controls the alignment of the beginning of the data for
1253  fixed size variables.
1254 
1255  `V_MINFREE`
1256 : Sets the pad at the end of the data for fixed size
1257  variables.
1258 
1259  `R_ALIGN`
1260 : Controls the alignment of the beginning of the data for
1261  variables which have an unlimited dimension (record variables).
1262 
1263 Errors
1264 ------
1265 
1266 NF\_\_ENDDEF returns the value NF\_NOERR if no errors occurred.
1267 Otherwise, the returned status indicates an error. Possible causes of
1268 errors include:
1269 
1270 - The specified netCDF dataset is not in define mode.
1271 - The specified netCDF ID does not refer to an open netCDF dataset.
1272 - The size of one or more variables exceed the size constraints for
1273  whichever variant of the file format is in use). See [(netcdf)Large
1274  File Support](netcdf.html#Large-File-Support) ‘Large File
1275  Support’ in The NetCDF Users Guide.
1276 
1277 Example
1278 -------
1279 
1280 Here is an example using NF\_\_ENDDEF to finish the definitions of a new
1281 netCDF dataset named foo.nc and put it into data mode:
1282 
1283  
1284 
1285 
1286 INCLUDE 'netcdf.inc'
1287  ...
1288 INTEGER NCID, STATUS, H_MINFREE, V_ALIGN, V_MINFREE, R_ALIGN
1289  ...
1290 STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
1291 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1292 
1293  ... ! create dimensions, variables, attributes
1294 
1295 H_MINFREE = 512
1296 V_ALIGN = 512
1297 V_MINFREE = 512
1298 R_ALIGN = 512
1299 STATUS = NF_ENDDEF(NCID, H_MINFREE, V_ALIGN, V_MINFREE, R_ALIGN)
1300 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1301 
1302 
1303 2.14 NF\_CLOSE
1304 --------------
1305 
1306 The function NF\_CLOSE closes an open netCDF dataset. If the dataset is
1307 in define mode, NF\_ENDDEF will be called before closing. (In this case,
1308 if NF\_ENDDEF returns an error, NF\_ABORT will automatically be called
1309 to restore the dataset to the consistent state before define mode was
1310 last entered.) After an open netCDF dataset is closed, its netCDF ID may
1311 be reassigned to the next netCDF dataset that is opened or created.
1312 
1313 Usage
1314 -----
1315 
1316  
1317 
1318 
1319 INTEGER FUNCTION NF_CLOSE(INTEGER NCID)
1320 
1321 
1322  `NCID`
1323 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1324 
1325 Errors
1326 ------
1327 
1328 NF\_CLOSE returns the value NF\_NOERR if no errors occurred. Otherwise,
1329 the returned status indicates an error. Possible causes of errors
1330 include:
1331 
1332 - Define mode was entered and the automatic call made to NF\_ENDDEF
1333  failed.
1334 - The specified netCDF ID does not refer to an open netCDF dataset.
1335 
1336 Example
1337 -------
1338 
1339 Here is an example using NF\_CLOSE to finish the definitions of a new
1340 netCDF dataset named foo.nc and release its netCDF ID:
1341 
1342  
1343 
1344 
1345 INCLUDE 'netcdf.inc'
1346  ...
1347 INTEGER NCID, STATUS
1348  ...
1349 STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
1350 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1351 
1352  ... ! create dimensions, variables, attributes
1353 
1354 STATUS = NF_CLOSE(NCID)
1355 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1356 
1357 
1358 2.15 NF\_INQ Family
1359 -------------------
1360 
1361 Members of the NF\_INQ family of functions return information about an
1362 open netCDF dataset, given its netCDF ID. Dataset inquire functions may
1363 be called from either define mode or data mode. The first function,
1364 NF\_INQ, returns values for the number of dimensions, the number of
1365 variables, the number of global attributes, and the dimension ID of the
1366 dimension defined with unlimited length, if any. The other functions in
1367 the family each return just one of these items of information.
1368 
1369 For FORTRAN, these functions include NF\_INQ, NF\_INQ\_NDIMS,
1370 NF\_INQ\_NVARS, NF\_INQ\_NATTS, and NF\_INQ\_UNLIMDIM. An additional
1371 function, NF\_INQ\_FORMAT, returns the (rarely needed) format version.
1372 
1373 No I/O is performed when these functions are called, since the required
1374 information is available in memory for each open netCDF dataset.
1375 
1376 Usage
1377 -----
1378 
1379  
1380 
1381 
1382 INTEGER FUNCTION NF_INQ (INTEGER NCID, INTEGER ndims,
1383  INTEGER nvars,INTEGER ngatts,
1384  INTEGER unlimdimid)
1385 INTEGER FUNCTION NF_INQ_NDIMS (INTEGER NCID, INTEGER ndims)
1386 INTEGER FUNCTION NF_INQ_NVARS (INTEGER NCID, INTEGER nvars)
1387 INTEGER FUNCTION NF_INQ_NATTS (INTEGER NCID, INTEGER ngatts)
1388 INTEGER FUNCTION NF_INQ_UNLIMDIM (INTEGER NCID, INTEGER unlimdimid)
1389 INTEGER FUNCTION NF_INQ_FORMAT (INTEGER NCID, INTEGER format)
1390 
1391 
1392  `NCID`
1393 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1394 
1395  `ndims`
1396 : Returned number of dimensions defined for this netCDF dataset.
1397 
1398  `nvars`
1399 : Returned number of variables defined for this netCDF dataset.
1400 
1401  `ngatts`
1402 : Returned number of global attributes defined for this netCDF
1403  dataset.
1404 
1405  `unlimdimid`
1406 : Returned ID of the unlimited dimension, if there is one for this
1407  netCDF dataset. If no unlimited length dimension has been defined,
1408  -1 is returned.
1409 
1410  `format`
1411 : Returned format version, one of NF\_FORMAT\_CLASSIC,
1412  NF\_FORMAT\_64BIT, NF\_FORMAT\_NETCDF4,
1413  NF\_FORMAT\_NETCDF4\_CLASSIC.
1414 
1415 Errors
1416 ------
1417 
1418 All members of the NF\_INQ family return the value NF\_NOERR if no
1419 errors occurred. Otherwise, the returned status indicates an error.
1420 Possible causes of errors include:
1421 
1422 - The specified netCDF ID does not refer to an open netCDF dataset.
1423 
1424 Example
1425 -------
1426 
1427 Here is an example using NF\_INQ to find out about a netCDF dataset
1428 named foo.nc:
1429 
1430  
1431 
1432 
1433 INCLUDE 'netcdf.inc'
1434  ...
1435 INTEGER STATUS, NCID, NDIMS, NVARS, NGATTS, UNLIMDIMID
1436  ...
1437 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
1438 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1439  ...
1440 STATUS = NF_INQ(NCID, NDIMS, NVARS, NGATTS, UNLIMDIMID)
1441 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1442 
1443 
1444 2.16 NF\_SYNC
1445 -------------
1446 
1447 The function NF\_SYNC offers a way to synchronize the disk copy of a
1448 netCDF dataset with in-memory buffers. There are two reasons you might
1449 want to synchronize after writes:
1450 
1451 - To minimize data loss in case of abnormal termination, or
1452 - To make data available to other processes for reading immediately
1453  after it is written. But note that a process that already had the
1454  dataset open for reading would not see the number of records
1455  increase when the writing process calls NF\_SYNC; to accomplish
1456  this, the reading process must call NF\_SYNC.
1457 
1458 This function is backward-compatible with previous versions of the
1459 netCDF library. The intent was to allow sharing of a netCDF dataset
1460 among multiple readers and one writer, by having the writer call
1461 NF\_SYNC after writing and the readers call NF\_SYNC before each read.
1462 For a writer, this flushes buffers to disk. For a reader, it makesre
1463 that the next read will be from disk rather than from previously cached
1464 buffers, so that the reader will see changes made by the writing process
1465 (e.g., the number of records written) without having to close and reopen
1466 the dataset. If you are only accessing a small amount of data, it can be
1467 expensive in computer resources to always synchronize to disk after
1468 every write, since you are giving up the benefits of buffering.
1469 
1470 An easier way to accomplish sharing (and what is now recommended) is to
1471 have the writer and readers open the dataset with the NF\_SHARE flag,
1472 and then it will not be necessary to call NF\_SYNC at all. However, the
1473 NF\_SYNC function still provides finer granularity than the NF\_SHARE
1474 flag, if only a few netCDF accesses need to be synchronized among
1475 processes.
1476 
1477 It is important to note that changes to the ancillary data,ch as
1478 attribute values, are not propagated automatically by use of the
1479 NF\_SHARE flag. Use of the NF\_SYNC function is still required for this
1480 purpose.
1481 
1482 Sharing datasets when the writer enters define mode to change the data
1483 schema requires extra care. In previous releases, after the writer left
1484 define mode, the readers were left looking at an old copy of the
1485 dataset, since the changes were made to a new copy. The only way readers
1486 could see the changes was by closing and reopening the dataset. Now the
1487 changes are made in place, but readers have no knowledge that their
1488 internal tables are now inconsistent with the new dataset schema. If
1489 netCDF datasets are shared across redefinition, some mechanism external
1490 to the netCDF library must be provided that prevents access by readers
1491 during redefinition and causes the readers to call NF\_SYNC before any
1492 subsequent access.
1493 
1494 When calling NF\_SYNC, the netCDF dataset must be in data mode. A netCDF
1495 dataset in define mode is synchronized to disk only when NF\_ENDDEF is
1496 called. A process that is reading a netCDF dataset that another process
1497 is writing may call NF\_SYNC to get updated with the changes made to the
1498 data by the writing process (e.g., the number of records written),
1499 without having to close and reopen the dataset.
1500 
1501 Data is automatically synchronized to disk when a netCDF dataset is
1502 closed, or whenever you leave define mode.
1503 
1504 Usage
1505 -----
1506 
1507  
1508 
1509 
1510 INTEGER FUNCTION NF_SYNC(INTEGER NCID)
1511 
1512 
1513  `NCID`
1514 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1515 
1516 Errors
1517 ------
1518 
1519 NF\_SYNC returns the value NF\_NOERR if no errors occurred. Otherwise,
1520 the returned status indicates an error. Possible causes of errors
1521 include:
1522 
1523 - The netCDF dataset is in define mode.
1524 - The specified netCDF ID does not refer to an open netCDF dataset.
1525 
1526 Example
1527 -------
1528 
1529 Here is an example using NF\_SYNC to synchronize the disk writes of a
1530 netCDF dataset named foo.nc:
1531 
1532  
1533 
1534 
1535 INCLUDE 'netcdf.inc'
1536  ...
1537 INTEGER STATUS, NCID
1538  ...
1539 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
1540 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1541  ...
1542 ! write data or change attributes
1543  ...
1544 STATUS = NF_SYNC(NCID)
1545 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1546 
1547 
1548 2.17 NF\_ABORT
1549 --------------
1550 
1551 You no longer need to call this function, since it is called
1552 automatically by NF\_CLOSE in case the dataset is in define mode and
1553 something goes wrong with committing the changes. The function NF\_ABORT
1554 just closes the netCDF dataset, if not in define mode. If the dataset is
1555 being created and is still in define mode, the dataset is deleted. If
1556 define mode was entered by a call to NF\_REDEF, the netCDF dataset is
1557 restored to its state before definition mode was entered and the dataset
1558 is closed.
1559 
1560 Usage
1561 -----
1562 
1563  
1564 
1565 
1566 INTEGER FUNCTION NF_ABORT(INTEGER NCID)
1567 
1568 
1569  `NCID`
1570 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1571 
1572 Errors
1573 ------
1574 
1575 NF\_ABORT returns the value NF\_NOERR if no errors occurred. Otherwise,
1576 the returned status indicates an error. Possible causes of errors
1577 include:
1578 
1579 - When called from define mode while creating a netCDF dataset,
1580  deletion of the dataset failed.
1581 - The specified netCDF ID does not refer to an open netCDF dataset.
1582 
1583 Example
1584 -------
1585 
1586 Here is an example using NF\_ABORT to back out of redefinitions of a
1587 dataset named foo.nc:
1588 
1589  
1590 
1591 
1592 INCLUDE 'netcdf.inc'
1593  ...
1594 INTEGER STATUS, NCID, LATID
1595  ...
1596 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
1597 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1598  ...
1599 STATUS = NF_REDEF(NCID)
1600 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1601  ...
1602 STATUS = NF_DEF_DIM(NCID, 'LAT', 18, LATID)
1603 IF (STATUS .NE. NF_NOERR) THEN ! dimension definition failed
1604  CALL HANDLE_ERR(STATUS)
1605  STATUS = NF_ABORT(NCID) ! abort redefinitions
1606  IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1607 ENDIF
1608 ...
1609 
1610 
1611 2.18 NF\_SET\_FILL
1612 ------------------
1613 
1614 This function is intended for advanced usage, to optimize writes under
1615 some circumstances described below. The function NF\_SET\_FILL sets the
1616 fill mode for a netCDF dataset open for writing and returns the current
1617 fill mode in a return parameter. The fill mode can be specified as
1618 either NF\_FILL or NF\_NOFILL. The default behavior corresponding to
1619 NF\_FILL is that data is pre-filled with fill values, that is fill
1620 values are written when you create non-record variables or when you
1621 write a value beyond data that has not yet been written. This makes it
1622 possible to detect attempts to read data before it was written. See
1623 section [Fill Values](#Fill-Values), for more information on the use of
1624 fill values. See [(netcdf)Attribute
1625 Conventions](netcdf.html#Attribute-Conventions) ‘Attribute
1626 Conventions’ in The NetCDF Users Guide, for information about how to
1627 define your own fill values.
1628 
1629 The behavior corresponding to NF\_NOFILL overrides the default behavior
1630 of prefilling data with fill values. This can be used to enhance
1631 performance, because it avoids the duplicate writes that occur when the
1632 netCDF library writes fill values that are later overwritten with data.
1633 
1634 A value indicating which mode the netCDF dataset was already in is
1635 returned. You can use this value to temporarily change the fill mode of
1636 an open netCDF dataset and then restore it to the previous mode.
1637 
1638 After you turn on NF\_NOFILL mode for an open netCDF dataset, you must
1639 be certain to write valid data in all the positions that will later be
1640 read. Note that nofill mode is only a transient property of a netCDF
1641 dataset open for writing: if you close and reopen the dataset, it will
1642 revert to the default behavior. You can also revert to the default
1643 behavior by calling NF\_SET\_FILL again to explicitly set the fill mode
1644 to NF\_FILL.
1645 
1646 There are three situations where it is advantageous to set nofill mode:
1647 
1648 1. Creating and initializing a netCDF dataset. In this case, you should
1649  set nofill mode before calling NF\_ENDDEF and then write completely
1650  all non-record variables and the initial records of all the record
1651  variables you want to initialize.
1652 2. Extending an existing record-oriented netCDF dataset. Set nofill
1653  mode after opening the dataset for writing, then append the
1654  additional records to the dataset completely, leaving no intervening
1655  unwritten records.
1656 3. Adding new variables that you are going to initialize to an existing
1657  netCDF dataset. Set nofill mode before calling NF\_ENDDEF then write
1658  all the new variables completely.
1659 
1660 If the netCDF dataset has an unlimited dimension and the last record was
1661 written while in nofill mode, then the dataset may be shorter than if
1662 nofill mode was not set, but this will be completely transparent if you
1663 access the data only through the netCDF interfaces.
1664 
1665 The use of this feature may not be available (or even needed) in future
1666 releases. Programmers are cautioned against heavy reliance upon this
1667 feature.
1668 
1669 Usage
1670 -----
1671 
1672  
1673 
1674 
1675 INTEGER FUNCTION NF_SET_FILL(INTEGER NCID, INTEGER FILLMODE,
1676  INTEGER old_mode)
1677 
1678 
1679  `NCID`
1680 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
1681 
1682  `FILLMODE`
1683 : Desired fill mode for the dataset, either NF\_NOFILL or NF\_FILL.
1684 
1685  `old_mode`
1686 : Returned current fill mode of the dataset before this call, either
1687  NF\_NOFILL or NF\_FILL.
1688 
1689 Errors
1690 ------
1691 
1692 NF\_SET\_FILL returns the value NF\_NOERR if no errors occurred.
1693 Otherwise, the returned status indicates an error. Possible causes of
1694 errors include:
1695 
1696 - The specified netCDF ID does not refer to an open netCDF dataset.
1697 - The specified netCDF ID refers to a dataset open for read-only
1698  access.
1699 - The fill mode argument is neither NF\_NOFILL nor NF\_FILL..
1700 
1701 Example
1702 -------
1703 
1704 Here is an example using NF\_SET\_FILL to set nofill mode forbsequent
1705 writes of a netCDF dataset named foo.nc:
1706 
1707  
1708 
1709 
1710 INCLUDE 'netcdf.inc'
1711  ...
1712 INTEGER NCID, STATUS, OMODE
1713  ...
1714 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
1715 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1716  ...
1717 ! write data with default prefilling behavior
1718  ...
1719 STATUS = NF_SET_FILL(NCID, NF_NOFILL, OMODE)
1720 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1721  ...
1722 ! write data with no prefilling
1723  ...
1724 
1725 
1726 2.19 NF\_SET\_DEFAULT\_FORMAT
1727 -----------------------------
1728 
1729 This function is intended for advanced users.
1730 
1731 In version 3.6, netCDF introduced a new data format, the first change in
1732 the underlying binary data format since the netCDF interface was
1733 released. The new format, 64-bit offset format, was introduced to
1734 greatly relax the limitations on creating very large files.
1735 
1736 In version 4.0, another new binary format was introduced: netCDF-4/HDF5.
1737 
1738 Users are warned that creating files in the 64-bit offset format makes
1739 them unreadable by the netCDF library prior to version 3.6.0, and
1740 creating files in netcdf-4/HDF5 format makes them unreadable by the
1741 netCDF library prior to version 4.0. For reasons of compatibility, users
1742 should continue to create files in netCDF classic format.
1743 
1744 Users who do want to use 64-bit offset or netCDF-4/HDF5 format files can
1745 create them directory from NF\_CREATE, using the proper cmode flag. (see
1746 section [NF\_CREATE](#NF_005fCREATE)).
1747 
1748 The function NF\_SET\_DEFAULT\_FORMAT allows the user to change the
1749 format of the netCDF file to be created by future calls to NF\_CREATE
1750 without changing the cmode flag.
1751 
1752 This allows the user to convert a program to use the new formats without
1753 changing all calls the NF\_CREATE.
1754 
1755 Once the default format is set, all future created files will be in the
1756 desired format.
1757 
1758 Constants are provided in the netcdf.inc file to be used with this
1759 function: nf\_format\_classic, nf\_format\_64bit, nf\_format\_netcdf4
1760 and nf\_format\_netcdf4\_classic.
1761 
1762 Usage
1763 -----
1764 
1765  
1766 
1767 
1768 INTEGER FUNCTION NF_SET_DEFAULT_FORMAT(INTEGER FORMAT, INTEGER OLD_FORMT)
1769 
1770 
1771  `FORMAT`
1772 : Either nf\_format\_classic, nf\_format\_64bit, nf\_format\_netcdf4
1773  or nf\_format\_netcdf4\_classic.
1774 
1775  `OLD_FORMAT`
1776 : The default format at the time the function is called is returned
1777  here.
1778 
1779 Errors
1780 ------
1781 
1782 The following error codes may be returned by this function:
1783 
1784 - An NF\_EINVAL error is returned if an invalid default format is
1785  specified.
1786 
1787 Example
1788 -------
1789 
1790  
1791 
1792 
1793 INCLUDE 'netcdf.inc'
1794  ...
1795 INTEGER STATUS, OLD_FORMAT
1796  ...
1797 STATUS = NF_SET_DEFAULT_FORMAT(nf_format_64bit, OLD_FORMAT)
1798 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
1799  ...
1800 
1801 
1802 2.20 Set HDF5 Chunk Cache for Future File Opens/Creates: NF\_SET\_CHUNK\_CACHE
1803 ------------------------------------------------------------------------------
1804 
1805 This function changes the chunk cache settings in the HDF5 library. The
1806 settings apply forbsequent file opens/creates. This function does not
1807 change the chunk cache settings of already open files.
1808 
1809 This affects the per-file chunk cache which the HDF5 layer maintains.
1810 The chunk cache size can be tuned for better performance.
1811 
1812 For more information, see the documentation for the H5Pset\_cache()
1813 function in the HDF5 library at the HDF5 website:
1814 [http://hdfgroup.org/HDF5/](http://hdfgroup.org/HDF5/).
1815 
1816 Usage
1817 -----
1818 
1819  
1820 
1821 
1822 INTEGER NF_SET_CHUNK_CACHE(INTEGER SIZE, INTEGER NELEMS, INTEGER PREEMPTION);
1823 
1824 
1825  `SIZE`
1826 : The total size of the raw data chunk cache in MegaBytes.
1827 
1828  `NELEMS`
1829 : The number slots in the per-variable chunk cache (should be a prime
1830  number larger than the number of chunks in the cache).
1831 
1832  `PREEMPTION`
1833 : The preemtion value must be between 0 and 100 inclusive and
1834  indicates how much chunks that have been fully read are favored for
1835  preemption. A value of zero means fully read chunks are treated no
1836  differently than other chunks (the preemption is strictly LRU) while
1837  a value of 100 means fully read chunks are always preempted before
1838  other chunks.
1839 
1840 Return Codes
1841 ------------
1842 
1843  `NF_NOERR`
1844 : No error.
1845 
1846  `NF_EINVAL`
1847 : Parameters size and nelems must be non-zero positive integers, and
1848  preemption must be between zero and 100 (inclusive). An NF\_EINVAL
1849  will be returned otherwise.
1850 
1851 
1852 
1853 2.21 Get the HDF5 Chunk Cache Settings for Future File Opens/Creates: NF\_GET\_CHUNK\_CACHE
1854 -------------------------------------------------------------------------------------------
1855 
1856 This function gets the chunk cache settings for the HDF5 library. The
1857 settings apply forbsequent file opens/creates.
1858 
1859 This affects the per-file chunk cache which the HDF5 layer maintains.
1860 The chunk cache size can be tuned for better performance.
1861 
1862 For more information, see the documentation for the H5Pget\_cache()
1863 function in the HDF5 library at the HDF5 website:
1864 [http://hdfgroup.org/HDF5/](http://hdfgroup.org/HDF5/).
1865 
1866 Usage
1867 -----
1868 
1869  
1870 
1871 
1872 INTEGER NC_GET_CHUNK_CACHE(INTEGER SIZE, INTEGER NELEMS, INTEGER PREEMPTION);
1873 
1874 
1875  `SIZE`
1876 : The total size of the raw data chunk cache will be put here.
1877 
1878  `NELEMS`
1879 : The number of chunk slots in the raw data chunk cache hash table
1880  will be put here.
1881 
1882  `PREEMPTION`
1883 : The preemption will be put here. The preemtion value is between 0
1884  and 100 inclusive and indicates how much chunks that have been fully
1885  read are favored for preemption. A value of zero means fully read
1886  chunks are treated no differently than other chunks (the preemption
1887  is strictly LRU) while a value of 100 means fully read chunks are
1888  always preempted before other chunks.
1889 
1890 Return Codes
1891 ------------
1892 
1893  `NC_NOERR`
1894 : No error.
1895 
1896 3. Groups
1897 =========
1898 
1899 NetCDF-4 addedpport for hierarchical groups within netCDF datasets.
1900 
1901 Groups are identified with a ncid, which identifies both the open file,
1902 and the group within that file. When a file is opened with NF\_OPEN or
1903 NF\_CREATE, the ncid for the root group of that file is provided. Using
1904 that as a starting point, users can add new groups, or list and navigate
1905 existing groups.
1906 
1907 All netCDF calls take a ncid which determines where the call will take
1908 its action. For example, the NF\_DEF\_VAR function takes a ncid as its
1909 first parameter. It will create a variable in whichever group its ncid
1910 refers to. Use the root ncid provided by NF\_CREATE or NF\_OPEN to
1911 create a variable in the root group. Or use NF\_DEF\_GRP to create a
1912 group and use its ncid to define a variable in the new group.
1913 
1914 Variable are only visible in the group in which they are defined. The
1915 same applies to attributes. “Global” attributes are defined in whichever
1916 group is refered to by the ncid.
1917 
1918 Dimensions are visible in their groups, and all child groups.
1919 
1920 Group operations are only permitted on netCDF-4 files - that is, files
1921 created with the HDF5 flag in nf\_create. (see
1922 [NF\_CREATE](#NF_005fCREATE)). Groups are not compatible with the netCDF
1923 classic data model, so files created with the NF\_CLASSIC\_MODEL file
1924 cannot contain groups (except the root group).
1925 
1926 3.1 Find a Group ID: NF\_INQ\_NCID
1927 ----------------------------------
1928 
1929 Given an ncid and group name (NULL or "" gets root group), return ncid
1930 of the named group.
1931 
1932 Usage
1933 -----
1934 
1935  
1936 
1937 
1938 INTEGER FUNCTION NF_INQ_NCID(INTEGER NCID, CHARACTER*(*) NAME, INTEGER GRPID)
1939 
1940 
1941  `NCID`
1942 : The group id for this operation.
1943 
1944  `NAME`
1945 : A character array that holds the name of the desired group. Must be
1946  less then NF\_MAX\_NAME.
1947 
1948  `GRPID`
1949 : The ID of the group will go here.
1950 
1951 Errors
1952 ------
1953 
1954  `NF_NOERR`
1955 : No error.
1956 
1957  `NF_EBADID`
1958 : Bad group id.
1959 
1960  `NF_ENOTNC4`
1961 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
1962  operations can only be performed on files defined with a create mode
1963  which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
1964 
1965  `NF_ESTRICTNC3`
1966 : This file was created with the strict netcdf-3 flag, therefore
1967  netcdf-4 operations are not allowed. (see
1968  [NF\_OPEN](#NF_005fOPEN)).
1969 
1970  `NF_EHDFERR`
1971 : An error was reported by the HDF5 layer.
1972 
1973 Example
1974 -------
1975 
1976 This example is from nf\_test/ftst\_groups.F.
1977 
1978  
1979 
1980 
1981 C Check getting the group by name
1982  retval = nf_inq_ncid(ncid, group_name, grpid_in)
1983  if (retval .ne. nf_noerr) call handle_err(retval)
1984 
1985 
1986 3.2 Get a List of Groups in a Group: NF\_INQ\_GRPS
1987 --------------------------------------------------
1988 
1989 Given a location id, return the number of groups it contains, and an
1990 array of their ncids.
1991 
1992 Usage
1993 -----
1994 
1995  
1996 
1997 
1998 INTEGER FUNCTION NF_INQ_GRPS(INTEGER NCID, INTEGER NUMGRPS, INTEGER NCIDS)
1999 
2000 
2001  `NCID`
2002 : The group id for this operation.
2003 
2004  `NUMGRPS`
2005 : An integer which will get number of groups in this group.
2006 
2007  `NCIDS`
2008 : An array of ints which will receive the IDs of all the groups in
2009  this group.
2010 
2011 Errors
2012 ------
2013 
2014  `NF_NOERR`
2015 : No error.
2016 
2017  `NF_EBADID`
2018 : Bad group id.
2019 
2020  `NF_ENOTNC4`
2021 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2022  operations can only be performed on files defined with a create mode
2023  which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2024 
2025  `NF_ESTRICTNC3`
2026 : This file was created with the strict netcdf-3 flag, therefore
2027  netcdf-4 operations are not allowed. (see
2028  [NF\_OPEN](#NF_005fOPEN)).
2029 
2030  `NF_EHDFERR`
2031 : An error was reported by the HDF5 layer.
2032 
2033 Example
2034 -------
2035 
2036 This example is from nf\_test/ftst\_groups.F.
2037 
2038  
2039 
2040 
2041 C What groups are there from the root group?
2042  retval = nf_inq_grps(ncid, ngroups_in, grpids)
2043  if (retval .ne. nf_noerr) call handle_err(retval)
2044 
2045 
2046 3.3 Find all the Variables in a Group: NF\_INQ\_VARIDS
2047 ------------------------------------------------------
2048 
2049 Find all varids for a location.
2050 
2051 Usage
2052 -----
2053 
2054  
2055 
2056 
2057 INTEGER FUNCTION NF_INQ_VARIDS(INTEGER NCID, INTEGERS VARIDS)
2058 
2059 
2060  `NCID`
2061 : The group id for this operation.
2062 
2063  `VARIDS`
2064 : An already allocated array to store the list of varids. Use
2065  nf\_inq\_nvars to find out how many variables there are. (see
2066  [NF\_INQ Family](#NF_005fINQ-Family)).
2067 
2068 Errors
2069 ------
2070 
2071  `NF_NOERR`
2072 : No error.
2073 
2074  `NF_EBADID`
2075 : Bad group id.
2076 
2077  `NF_ENOTNC4`
2078 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2079  operations can only be performed on files defined with a create mode
2080  which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2081 
2082  `NF_ESTRICTNC3`
2083 : This file was created with the strict netcdf-3 flag, therefore
2084  netcdf-4 operations are not allowed. (see
2085  [NF\_OPEN](#NF_005fOPEN)).
2086 
2087  `NF_EHDFERR`
2088 : An error was reported by the HDF5 layer.
2089 
2090 Example
2091 -------
2092 
2093 This example is from nf\_test/ftst\_groups.F.
2094 
2095  
2096 
2097 
2098 C Check varids inbgroup.
2099  retval = nf_inq_varidsbgrp_in, nvars, varids_in)
2100  if (retval .ne. nf_noerr) call handle_err(retval)
2101 
2102 
2103 3.4 Find all Dimensions Visible in a Group: NF\_INQ\_DIMIDS
2104 -----------------------------------------------------------
2105 
2106 Find all dimids for a location. This finds all dimensions in a group, or
2107 any of its parents.
2108 
2109 Usage
2110 -----
2111 
2112  
2113 
2114 
2115 INTEGER FUNCTION NF_INQ_DIMIDS(INTEGER NCID, INTEGER NDIMS, INTEGER DIMIDS, INTEGER INCLUDE_PARENTS)
2116 
2117 
2118  `NCID`
2119 : The group id for this operation.
2120 
2121  `NDIMS`
2122 : Returned number of dimensions for this location. If INCLUDE\_PARENTS
2123  is non-zero, number of dimensions visible from this group, which
2124  includes dimensions in parent groups.
2125 
2126  `DIMIDS`
2127 : An array of ints when the dimids of the visible dimensions will be
2128  stashed. Use nf\_inq\_ndims to find out how many dims are visible
2129  from this group. (see [NF\_INQ Family](#NF_005fINQ-Family)).
2130 
2131  `INCLUDE_PARENTS`
2132 : If zero, only the group specified by NCID will be searched for
2133  dimensions. Otherwise parent groups will be searched too.
2134 
2135 Errors
2136 ------
2137 
2138  `NF_NOERR`
2139 : No error.
2140 
2141  `NF_EBADID`
2142 : Bad group id.
2143 
2144  `NF_ENOTNC4`
2145 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2146  operations can only be performed on files defined with a create mode
2147  which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2148 
2149  `NF_ESTRICTNC3`
2150 : This file was created with the strict netcdf-3 flag, therefore
2151  netcdf-4 operations are not allowed. (see
2152  [NF\_OPEN](#NF_005fOPEN)).
2153 
2154  `NF_EHDFERR`
2155 : An error was reported by the HDF5 layer.
2156 
2157 Example
2158 -------
2159 
2160 This example is from nf\_test/ftst\_groups.F.
2161 
2162  
2163 
2164 
2165 C Check dimids inbgroup.
2166  retval = nf_inq_dimidsbgrp_in, ndims, dimids_in, 0)
2167  if (retval .ne. nf_noerr) call handle_err(retval)
2168  if (ndims .ne. 2 .or. dimids_in(1) .ne. dimids(1) .or.
2169  & dimids_in(2) .ne. dimids(2)) stop 2
2170 
2171 
2172 3.5 Find the Length of a Group’s Name: NF\_INQ\_GRPNAME\_LEN
2173 ------------------------------------------------------------
2174 
2175 Given ncid, find length of the full name. (Root group is named "/", with
2176 length 1.)
2177 
2178 Usage
2179 -----
2180 
2181  
2182 
2183 
2184 INTEGER FUNCTION NF_INQ_GRPNAME_LEN(INTEGER NCID, INTEGER LEN)
2185 
2186 
2187  `NCID`
2188 : The group id for this operation.
2189 
2190  `LEN`
2191 : An integer where the length will be placed.
2192 
2193 Errors
2194 ------
2195 
2196  `NF_NOERR`
2197 : No error.
2198 
2199  `NF_EBADID`
2200 : Bad group id.
2201 
2202  `NF_ENOTNC4`
2203 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2204  operations can only be performed on files defined with a create mode
2205  which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2206 
2207  `NF_ESTRICTNC3`
2208 : This file was created with the strict netcdf-3 flag, therefore
2209  netcdf-4 operations are not allowed. (see
2210  [NF\_OPEN](#NF_005fOPEN)).
2211 
2212  `NF_EHDFERR`
2213 : An error was reported by the HDF5 layer.
2214 
2215 Example
2216 -------
2217 
2218 This example is from nf\_test/ftst\_groups.F.
2219 
2220  
2221 
2222 
2223 C Check the length of the full name.
2224  retval = nf_inq_grpname_len(grpids(1), full_name_len)
2225  if (retval .ne. nf_noerr) call handle_err(retval)
2226 
2227 
2228 3.6 Find a Group’s Name: NF\_INQ\_GRPNAME
2229 -----------------------------------------
2230 
2231 Given ncid, find relative name of group. (Root group is named "/").
2232 
2233 The name provided by this function is relative to the parent group. For
2234 a full path name for the group is, with all parent groups included,
2235 separated with a forward slash (as in Unix directory names) See
2236 [Find a Group’s Full Name:
2237 NF\_INQ\_GRPNAME\_FULL](#NF_005fINQ_005fGRPNAME_005fFULL).
2238 
2239 Usage
2240 -----
2241 
2242  
2243 
2244 
2245 INTEGER FUNCTION NF_INQ_GRPNAME(INTEGER NCID, CHARACTER*(*) NAME)
2246 
2247 
2248 `NCID`
2249 
2250 The group id for this operation.
2251 
2252 `NAME`
2253 
2254 The name of the group will be copied to this character array. The name
2255 will be less than NF\_MAX\_NAME in length.
2256 
2257 ``
2258 
2259 Errors
2260 ------
2261 
2262  `NF_NOERR`
2263 : No error.
2264 
2265  `NF_EBADID`
2266 : Bad group id.
2267 
2268  `NF_ENOTNC4`
2269 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2270  operations can only be performed on files defined with a create mode
2271  which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2272 
2273  `NF_ESTRICTNC3`
2274 : This file was created with the strict netcdf-3 flag, therefore
2275  netcdf-4 operations are not allowed. (see
2276  [NF\_OPEN](#NF_005fOPEN)).
2277 
2278  `NF_EHDFERR`
2279 : An error was reported by the HDF5 layer.
2280 
2281 Example
2282 -------
2283 
2284 This example is from nf\_test/ftst\_groups.F.
2285 
2286  
2287 
2288 
2289 C Check the name of the root group.
2290  retval = nf_inq_grpname(ncid, name_in)
2291  if (retval .ne. nf_noerr) call handle_err(retval)
2292  if (name_in(1:1) .ne. '/') stop 2
2293 
2294 
2295 
2296 3.7 Find a Group’s Full Name: NF\_INQ\_GRPNAME\_FULL
2297 ----------------------------------------------------
2298 
2299 Given ncid, find complete name of group. (Root group is named "/").
2300 
2301 The name provided by this function is a full path name for the group is,
2302 with all parent groups included, separated with a forward slash (as in
2303 Unix directory names). For a name relative to the parent group See
2304 section [Find a Group’s Name:
2305 NF\_INQ\_GRPNAME](#NF_005fINQ_005fGRPNAME).
2306 
2307 To find the length of the full name See [Find the Length of a
2308 Group’s Name: NF\_INQ\_GRPNAME\_LEN](#NF_005fINQ_005fGRPNAME_005fLEN).
2309 
2310 Usage
2311 -----
2312 
2313  
2314 
2315 
2316 INTEGER FUNCTION NF_INQ_GRPNAME_FULL(INTEGER NCID, INTEGER LEN, CHARACTER*(*) NAME)
2317 
2318 
2319  `NCID`
2320 : The group id for this operation.
2321 
2322  `LEN`
2323 : The length of the full group name will go here.
2324 
2325  `NAME`
2326 : The name of the group will be copied to this character array.
2327 
2328 Errors
2329 ------
2330 
2331  `NF_NOERR`
2332 : No error.
2333 
2334  `NF_EBADID`
2335 : Bad group id.
2336 
2337  `NF_ENOTNC4`
2338 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2339  operations can only be performed on files defined with a create mode
2340  which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2341 
2342  `NF_ESTRICTNC3`
2343 : This file was created with the strict netcdf-3 flag, therefore
2344  netcdf-4 operations are not allowed. (see
2345  [NF\_OPEN](#NF_005fOPEN)).
2346 
2347  `NF_EHDFERR`
2348 : An error was reported by the HDF5 layer.
2349 
2350 Example
2351 -------
2352 
2353 This example is from nf\_test/ftst\_groups.F.
2354 
2355  
2356 
2357 
2358 C Check the full name.
2359  retval = nf_inq_grpname_full(grpids(1), full_name_len, name_in2)
2360  if (retval .ne. nf_noerr) call handle_err(retval)
2361 
2362 
2363 3.8 Find a Group’s Parent: NF\_INQ\_GRP\_PARENT
2364 -----------------------------------------------
2365 
2366 Given ncid, find the ncid of the parent group.
2367 
2368 When used with the root group, this function returns the NF\_ENOGRP
2369 error (since the root group has no parent.)
2370 
2371 Usage
2372 -----
2373 
2374  
2375 
2376 
2377 INTEGER FUNCTION NF_INQ_GRP_PARENT(INTEGER NCID, INTEGER PARENT_NCID)
2378 
2379 
2380  `NCID`
2381 : The group id.
2382 
2383  `PARENT_NCID`
2384 : The ncid of the parent group will be copied here.
2385 
2386 Errors
2387 ------
2388 
2389  `NF_NOERR`
2390 : No error.
2391 
2392  `NF_EBADID`
2393 : Bad group id.
2394 
2395  `NF_ENOGRP`
2396 : No parent group found (i.e. this is the root group).
2397 
2398  `NF_ENOTNC4`
2399 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2400  operations can only be performed on files defined with a create mode
2401  which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2402 
2403  `NF_ESTRICTNC3`
2404 : This file was created with the strict netcdf-3 flag, therefore
2405  netcdf-4 operations are not allowed. (see
2406  [NF\_OPEN](#NF_005fOPEN)).
2407 
2408  `NF_EHDFERR`
2409 : An error was reported by the HDF5 layer.
2410 
2411 Example
2412 -------
2413 
2414 This example is from nf\_test/ftst\_groups.F.
2415 
2416  
2417 
2418 
2419 C Check the parent ncid.
2420  retval = nf_inq_grp_parent(grpids(1), grpid_in)
2421  if (retval .ne. nf_noerr) call handle_err(retval)
2422 
2423 
2424 3.9 Find a Group by Name: NF\_INQ\_GRP\_NCID
2425 --------------------------------------------
2426 
2427 Given a group name an an ncid, find the ncid of the group id.
2428 
2429 Usage
2430 -----
2431 
2432  
2433 
2434 
2435 INTEGER FUNCTION NF_INQ_GRP_NCID(INTEGER NCID, CHARACTER GRP_NAME, INTEGER GRP_NCID)
2436 
2437 
2438  `NCID`
2439 : The group id to look in.
2440 
2441  `GRP_NAME`
2442 : The name of the group that should be found.
2443 
2444  `GRP_NCID`
2445 : This will get the group id, if it is found.
2446 
2447 Return Codes
2448 ------------
2449 
2450 The following return codes may be returned by this function.
2451 
2452  `NF_NOERR`
2453 : No error.
2454 
2455  `NF_EBADID`
2456 : Bad group id.
2457 
2458  `NF_EINVAL`
2459 : No name provided or name longer than NF\_MAX\_NAME.
2460 
2461  `NF_ENOGRP`
2462 : Named group not found.
2463 
2464  `NF_ENOTNC4`
2465 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2466  operations can only be performed on files defined with a create mode
2467  which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2468 
2469  `NF_ESTRICTNC3`
2470 : This file was created with the strict netcdf-3 flag, therefore
2471  netcdf-4 operations are not allowed. (see
2472  [NF\_OPEN](#NF_005fOPEN)).
2473 
2474  `NF_EHDFERR`
2475 : An error was reported by the HDF5 layer.
2476 
2477 Example
2478 -------
2479 
2480 This example is from nf\_test/ftst\_types3.F.
2481 
2482  
2483 
2484 
2485 C Go to a child group and find the id of our type.
2486  retval = nf_inq_grp_ncid(ncid, group_name,b_grpid)
2487  if (retval .ne. nf_noerr) call handle_err(retval)
2488 
2489 
2490 3.10 Find a Group by its Fully-qualified Name: NF\_INQ\_GRP\_FULL\_NCID
2491 -----------------------------------------------------------------------
2492 
2493 Given a fully qualified group name an an ncid, find the ncid of the
2494 group id.
2495 
2496 Usage
2497 -----
2498 
2499  
2500 
2501 
2502 INTEGER FUNCTION NF_INQ_GRP_FULL_NCID(INTEGER NCID, CHARACTER FULL_NAME, INTEGER GRP_NCID)
2503 
2504 
2505  `NCID`
2506 : The group id to look in.
2507 
2508  `FULL_NAME`
2509 : The fully-qualified group name.
2510 
2511  `GRP_NCID`
2512 : This will get the group id, if it is found.
2513 
2514 Return Codes
2515 ------------
2516 
2517 The following return codes may be returned by this function.
2518 
2519  `NF_NOERR`
2520 : No error.
2521 
2522  `NF_EBADID`
2523 : Bad group id.
2524 
2525  `NF_EINVAL`
2526 : No name provided or name longer than NF\_MAX\_NAME.
2527 
2528  `NF_ENOGRP`
2529 : Named group not found.
2530 
2531  `NF_ENOTNC4`
2532 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2533  operations can only be performed on files defined with a create mode
2534  which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2535 
2536  `NF_ESTRICTNC3`
2537 : This file was created with the strict netcdf-3 flag, therefore
2538  netcdf-4 operations are not allowed. (see
2539  [NF\_OPEN](#NF_005fOPEN)).
2540 
2541  `NF_EHDFERR`
2542 : An error was reported by the HDF5 layer.
2543 
2544 Example
2545 -------
2546 
2547 This example is from nf\_test/ftst\_groups.F.
2548 
2549  
2550 
2551 
2552 C Check the full name of the root group (also "/").
2553  retval = nf_inq_grpname_full(ncid, full_name_len, name_in)
2554  if (retval .ne. nf_noerr) call handle_err(retval)
2555 
2556 
2557 3.11 Create a New Group: NF\_DEF\_GRP
2558 -------------------------------------
2559 
2560 Create a group. Its location id is returned in new\_ncid.
2561 
2562 Usage
2563 -----
2564 
2565  
2566 
2567 
2568 INTEGER FUNCTION NF_DEF_GRP(INTEGER PARENT_NCID, CHARACTER*(*) NAME,
2569  INTEGER NEW_NCID)
2570 
2571 
2572  `PARENT_NCID`
2573 : The group id of the parent group.
2574 
2575  `NAME`
2576 : The name of the new group, which must be different from the name of
2577  any variable within the same parent group.
2578 
2579  `NEW_NCID`
2580 : The ncid of the new group will be placed there.
2581 
2582 Errors
2583 ------
2584 
2585  `NF_NOERR`
2586 : No error.
2587 
2588  `NF_EBADID`
2589 : Bad group id.
2590 
2591  `NF_ENAMEINUSE`
2592 : That name is in use. Group names must be unique within a group.
2593 
2594  `NF_EMAXNAME`
2595 : Name exceed max length NF\_MAX\_NAME.
2596 
2597  `NF_EBADNAME`
2598 : Name contains illegal characters.
2599 
2600  `NF_ENOTNC4`
2601 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
2602  operations can only be performed on files defined with a create mode
2603  which includes flag HDF5. (see [NF\_OPEN](#NF_005fOPEN)).
2604 
2605  `NF_ESTRICTNC3`
2606 : This file was created with the strict netcdf-3 flag, therefore
2607  netcdf-4 operations are not allowed. (see
2608  [NF\_OPEN](#NF_005fOPEN)).
2609 
2610  `NF_EHDFERR`
2611 : An error was reported by the HDF5 layer.
2612 
2613  `NF_EPERM`
2614 : Attempt to write to a read-only file.
2615 
2616  `NF_ENOTINDEFINE`
2617 : Not in define mode.
2618 
2619 Example
2620 -------
2621 
2622 In this exampe rom nf\_test/ftst\_groups.F, a groups is reated, and then
2623 ab-group is created in that group.
2624 
2625  
2626 
2627 
2628 C Create the netCDF file.
2629  retval = nf_create(file_name, NF_NETCDF4, ncid)
2630  if (retval .ne. nf_noerr) call handle_err(retval)
2631 
2632 C Create a group and abgroup.
2633  retval = nf_def_grp(ncid, group_name, grpid)
2634  if (retval .ne. nf_noerr) call handle_err(retval)
2635  retval = nf_def_grp(grpid,b_group_name,b_grpid)
2636  if (retval .ne. nf_noerr) call handle_err(retval)
2637 
2638 
2639 4. Dimensions
2640 =============
2641 
2642 4.1 Dimensions Introduction
2643 ---------------------------
2644 
2645 Dimensions for a netCDF dataset are defined when it is created, while
2646 the netCDF dataset is in define mode. Additional dimensions may be added
2647 later by reentering define mode. A netCDF dimension has a name and a
2648 length. At most one dimension in a netCDF dataset can have the unlimited
2649 length, which means variables using this dimension can grow along this
2650 dimension.
2651 
2652 There is aggested limit (100) to the number of dimensions that can be
2653 defined in a single netCDF dataset. The limit is the value of the
2654 predefined macro NF\_MAX\_DIMS. The purpose of the limit is to make
2655 writing generic applications simpler. They need only provide an array of
2656 NF\_MAX\_DIMS dimensions to handle any netCDF dataset. The
2657 implementation of the netCDF library does not enforce this advisory
2658 maximum, so it is possible to use more dimensions, if necessary, but
2659 netCDF utilities that ame the advisory maximums may not be able to
2660 handle the rlting netCDF datasets.
2661 
2662 Ordinarily, the name and length of a dimension are fixed when the
2663 dimension is first defined. The name may be changed later, but the
2664 length of a dimension (other than the unlimited dimension) cannot be
2665 changed without copying all the data to a new netCDF dataset with a
2666 redefined dimension length.
2667 
2668 A netCDF dimension in an open netCDF dataset is referred to by a small
2669 integer called a dimension ID. In the FORTRAN interface, dimension IDs
2670 are 1, 2, 3, ..., in the order in which the dimensions were defined.
2671 
2672 Operationspported on dimensions are:
2673 
2674 - Create a dimension, given its name and length.
2675 - Get a dimension ID from its name.
2676 - Get a dimension’s name and length from its ID.
2677 - Rename a dimension.
2678 
2679 4.2 NF\_DEF\_DIM
2680 ----------------
2681 
2682 The function NF\_DEF\_DIM adds a new dimension to an open netCDF dataset
2683 in define mode. It returns (as an argument) a dimension ID, given the
2684 netCDF ID, the dimension name, and the dimension length. At most one
2685 unlimited length dimension, called the record dimension, may be defined
2686 for each netCDF dataset.
2687 
2688 Usage
2689 -----
2690 
2691  
2692 
2693 
2694 INTEGER FUNCTION NF_DEF_DIM (INTEGER NCID, CHARACTER*(*) NAME,
2695  INTEGER LEN, INTEGER dimid)
2696 
2697 
2698  `NCID`
2699 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
2700 
2701  `NAME`
2702 : Dimension name.
2703 
2704  `LEN`
2705 : Length of dimension; that is, number of values for this dimension as
2706  an index to variables that use it. This should be either a positive
2707  integer or the predefined constant NF\_UNLIMITED.
2708 
2709  `dimid`
2710 : Returned dimension ID.
2711 
2712 Errors
2713 ------
2714 
2715 NF\_DEF\_DIM returns the value NF\_NOERR if no errors occurred.
2716 Otherwise, the returned status indicates an error. Possible causes of
2717 errors include:
2718 
2719 - The netCDF dataset is not in definition mode.
2720 - The specified dimension name is the name of another existing
2721  dimension.
2722 - The specified length is not greater than zero.
2723 - The specified length is unlimited, but there is already an unlimited
2724  length dimension defined for this netCDF dataset.
2725 - The specified netCDF ID does not refer to an open netCDF dataset.
2726 
2727 Example
2728 -------
2729 
2730 Here is an example using NF\_DEF\_DIM to create a dimension named lat of
2731 length 18 and a unlimited dimension named rec in a new netCDF dataset
2732 named foo.nc:
2733 
2734  
2735 
2736 
2737 INCLUDE 'netcdf.inc'
2738  ...
2739 INTEGER STATUS, NCID, LATID, RECID
2740  ...
2741 STATUS = NF_CREATE('foo.nc', NF_NOCLOBBER, NCID)
2742 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2743  ...
2744 STATUS = NF_DEF_DIM(NCID, 'lat', 18, LATID)
2745 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2746 STATUS = NF_DEF_DIM(NCID, 'rec', NF_UNLIMITED, RECID)
2747 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2748 
2749 
2750 4.3 NF\_INQ\_DIMID
2751 ------------------
2752 
2753 The function NF\_INQ\_DIMID returns (as an argument) the ID of a netCDF
2754 dimension, given the name of the dimension. If ndims is the number of
2755 dimensions defined for a netCDF dataset, each dimension has an ID
2756 between 1 and ndims.
2757 
2758 Usage
2759 -----
2760 
2761  
2762 
2763 
2764 INTEGER FUNCTION NF_INQ_DIMID (INTEGER NCID, CHARACTER*(*) NAME,
2765  INTEGER dimid)
2766 
2767 
2768  `NCID`
2769 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
2770 
2771  `NAME`
2772 : Dimension name.
2773 
2774  `dimid`
2775 : Returned dimension ID.
2776 
2777 Errors
2778 ------
2779 
2780 NF\_INQ\_DIMID returns the value NF\_NOERR if no errors occurred.
2781 Otherwise, the returned status indicates an error. Possible causes of
2782 errors include:
2783 
2784 - The name that was specified is not the name of a dimension in the
2785  netCDF dataset.
2786 - The specified netCDF ID does not refer to an open netCDF dataset.
2787 
2788 Example
2789 -------
2790 
2791 Here is an example using NF\_INQ\_DIMID to determine the dimension ID of
2792 a dimension named lat, amed to have been defined previously in an
2793 existing netCDF dataset named foo.nc:
2794 
2795  
2796 
2797 
2798 INCLUDE 'netcdf.inc'
2799  ...
2800 INTEGER STATUS, NCID, LATID
2801  ...
2802 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
2803 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2804  ...
2805 STATUS = NF_INQ_DIMID(NCID, 'lat', LATID)
2806 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2807 
2808 
2809 4.4 NF\_INQ\_DIM Family
2810 -----------------------
2811 
2812 This family of functions returns information about a netCDF dimension.
2813 Information about a dimension includes its name and its length. The
2814 length for the unlimited dimension, if any, is the number of records
2815 written so far.
2816 
2817 The functions in this family include NF\_INQ\_DIM, NF\_INQ\_DIMNAME, and
2818 NF\_INQ\_DIMLEN. The function NF\_INQ\_DIM returns all the information
2819 about a dimension; the other functions each return just one item of
2820 information.
2821 
2822 Usage
2823 -----
2824 
2825  
2826 
2827 
2828 INTEGER FUNCTION NF_INQ_DIM (INTEGER NCID, INTEGER DIMID,
2829  CHARACTER*(*) name, INTEGER len)
2830 INTEGER FUNCTION NF_INQ_DIMNAME (INTEGER NCID, INTEGER DIMID,
2831  CHARACTER*(*) name)
2832 INTEGER FUNCTION NF_INQ_DIMLEN (INTEGER NCID, INTEGER DIMID,
2833  INTEGER len)
2834 
2835 
2836  `NCID`
2837 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
2838 
2839  `DIMID`
2840 : Dimension ID, from a previous call to NF\_INQ\_DIMID or
2841  NF\_DEF\_DIM.
2842 
2843  `NAME`
2844 : Returned dimension name. The caller must allocate space for the
2845  returned name. The maximum possible length, in characters, of a
2846  dimension name is given by the predefined constant NF\_MAX\_NAME.
2847 
2848  `len`
2849 : Returned length of dimension. For the unlimited dimension, this is
2850  the current maximum value used for writing any variables with this
2851  dimension, that is the maximum record number.
2852 
2853 Errors
2854 ------
2855 
2856 These functions return the value NF\_NOERR if no errors occurred.
2857 Otherwise, the returned status indicates an error. Possible causes of
2858 errors include:
2859 
2860 - The dimension ID is invalid for the specified netCDF dataset.
2861 - The specified netCDF ID does not refer to an open netCDF dataset.
2862 
2863 Example
2864 -------
2865 
2866 Here is an example using NF\_INQ\_DIM to determine the length of a
2867 dimension named lat, and the name and current maximum length of the
2868 unlimited dimension for an existing netCDF dataset named foo.nc:
2869 
2870  
2871 
2872 
2873 INCLUDE 'netcdf.inc'
2874  ...
2875 INTEGER STATUS, NCID, LATID, LATLEN, RECID, NRECS
2876 CHARACTER*(NF_MAX_NAME) LATNAM, RECNAM
2877  ...
2878 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
2879 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2880 ! get ID of unlimited dimension
2881 STATUS = NF_INQ_UNLIMDIM(NCID, RECID)
2882 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2883  ...
2884 STATUS = NF_INQ_DIMID(NCID, 'lat', LATID)
2885 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2886 ! get lat length
2887 STATUS = NF_INQ_DIMLEN(NCID, LATID, LATLEN)
2888 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2889 ! get unlimited dimension name and current length
2890 STATUS = NF_INQ_DIM(NCID, RECID, RECNAME, NRECS)
2891 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2892 
2893 
2894 4.5 NF\_RENAME\_DIM
2895 -------------------
2896 
2897 The function NF\_RENAME\_DIM renames an existing dimension in a netCDF
2898 dataset open for writing. If the new name is longer than the old name,
2899 the netCDF dataset must be in define mode. You cannot rename a dimension
2900 to have the same name as another dimension.
2901 
2902 Usage
2903 -----
2904 
2905  
2906 
2907 
2908 INTEGER FUNCTION NF_RENAME_DIM (INTEGER NCID, INTEGER DIMID,
2909  CHARACTER*(*) NAME)
2910 
2911 
2912  `NCID`
2913 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
2914 
2915  `DIMID`
2916 : Dimension ID, from a previous call to NF\_INQ\_DIMID or
2917  NF\_DEF\_DIM.
2918 
2919  `NAME`
2920 : New dimension name.
2921 
2922 Errors
2923 ------
2924 
2925 NF\_RENAME\_DIM returns the value NF\_NOERR if no errors occurred.
2926 Otherwise, the returned status indicates an error. Possible causes of
2927 errors include:
2928 
2929 - The new name is the name of another dimension.
2930 - The dimension ID is invalid for the specified netCDF dataset.
2931 - The specified netCDF ID does not refer to an open netCDF dataset.
2932 - The new name is longer than the old name and the netCDF dataset is
2933  not in define mode.
2934 
2935 Example
2936 -------
2937 
2938 Here is an example using NF\_RENAME\_DIM to rename the dimension lat to
2939 latitude in an existing netCDF dataset named foo.nc:
2940 
2941  
2942 
2943 
2944 INCLUDE 'netcdf.inc'
2945  ...
2946 INTEGER STATUS, NCID, LATID
2947  ...
2948 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
2949 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2950  ...
2951 ! put in define mode to rename dimension
2952 STATUS = NF_REDEF(NCID)
2953 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2954 STATUS = NF_INQ_DIMID(NCID, 'lat', LATID)
2955 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2956 STATUS = NF_RENAME_DIM(NCID, LATID, 'latitude')
2957 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2958 ! leave define mode
2959 STATUS = NF_ENDDEF(NCID)
2960 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
2961 
2962 
2963 5. User Defined Data Types
2964 ==========================
2965 
2966 5.1 User Defined Types Introduction
2967 -----------------------------------
2968 
2969 NetCDF-4 has addedpport for four different user defined data types.
2970 
2971  `compound type`
2972 : Like a C struct, a compound type is a collection of types, including
2973  other user defined types, in one package.
2974 
2975  `variable length array type`
2976 : The variable length array may be used to store ragged arrays.
2977 
2978  `opaque type`
2979 : This type has only a size per element, and no other type
2980  information.
2981 
2982  `enum type`
2983 : Like an enumeration in C, this type lets you assign text values to
2984  integer values, and store the integer values.
2985 
2986 Users may construct user defined type with the various NF\_DEF\_\*
2987 functions described in this. They may learn about user defined
2988 types by using the NF\_INQ\_ functions defined in this.
2989 
2990 Once types are constructed, define variables of the new type with
2991 NF\_DEF\_VAR (see [Create a Variable:
2992 `NF_DEF_VAR`](#NF_005fDEF_005fVAR)). Write to them with NF\_PUT\_VAR1,
2993 NF\_PUT\_VAR, NF\_PUT\_VARA, or NF\_PUT\_VARS (see
2994 [Variables](#Variables)). Read data of user-defined type with
2995 NF\_GET\_VAR1, NF\_GET\_VAR, NF\_GET\_VARA, or NF\_GET\_VARS (see
2996 section [Variables](#Variables)).
2997 
2998 Create attributes of the new type with NF\_PUT\_ATT (see
2999 [NF\_PUT\_ATT\_ type](#NF_005fPUT_005fATT_005f-type)). Read attributes
3000 of the new type with NF\_GET\_ATT (see [NF\_GET\_ATT\_
3001 type](#NF_005fGET_005fATT_005f-type)).
3002 
3003 5.2 Learn the IDs of All Types in Group: NF\_INQ\_TYPEIDS
3004 ---------------------------------------------------------
3005 
3006 Learn the number of types defined in a group, and their IDs.
3007 
3008 Usage
3009 -----
3010 
3011 
3012 
3013 INTEGER FUNCTION NF_INQ_TYPEIDS(INTEGER NCID, INTEGER NTYPES,
3014  INTEGER TYPEIDS)
3015 
3016 
3017  `NCID`
3018 : The group id.
3019 
3020  `NTYPES`
3021 : A pointer to int which will get the number of types defined in the
3022  group. If NULL, ignored.
3023 
3024  `TYPEIDS`
3025 : A pointer to an int array which will get the typeids. If NULL,
3026  ignored.
3027 
3028 Errors
3029 ------
3030 
3031  `NF_NOERR`
3032 : No error.
3033 
3034  `NF_BADID`
3035 : Bad ncid.
3036 
3037 Example
3038 -------
3039 
3040 The following example is from the test program nf\_test/ftst\_vars3.F.
3041 
3042  
3043 
3044 
3045  retval = nf_inq_typeids(ncid, num_types, typeids)
3046  if (retval .ne. nf_noerr) call handle_err(retval)
3047 
3048 
3049 
3050 5.3 Find a Typeid from Group and Name: NF\_INQ\_TYPEID
3051 ------------------------------------------------------
3052 
3053 Given a group ID and a type name, find the ID of the type. If the type
3054 is not found in the group, then the parents are searched. If still not
3055 found, the entire file is searched.
3056 
3057 Usage
3058 -----
3059 
3060  
3061 
3062 
3063 INTEGER FUNCTION NF_INQ_TYPEID(INTEGER NCID, CHARACTER NAME, NF_TYPE TYPEIDP)
3064 
3065 
3066  `NCID`
3067 : The group id.
3068 
3069  `NAME`
3070 : The name of a type.
3071 
3072  `TYPEIDP`
3073 : The typeid of the named type (if found).
3074 
3075 Errors
3076 ------
3077 
3078  `NF_NOERR`
3079 : No error.
3080 
3081  `NF_EBADID`
3082 : Bad ncid.
3083 
3084  `NF_EBADTYPE`
3085 : Can’t find type.
3086 
3087 Example
3088 -------
3089 
3090 The following example is from nf\_test/ftst\_types3.F:
3091 
3092  
3093 
3094 
3095 C Go to a child group and find the id of our type.
3096  retval = nf_inq_grp_ncid(ncid, group_name,b_grpid)
3097  if (retval .ne. nf_noerr) call handle_err(retval)
3098  retval = nf_inq_typeidb_grpid, type_name, typeid_in)
3099  if (retval .ne. nf_noerr) call handle_err(retval)
3100 
3101 
3102 5.4 Learn About a User Defined Type: NF\_INQ\_TYPE
3103 --------------------------------------------------
3104 
3105 Given an ncid and a typeid, get the information about a type. This
3106 function will work on any type, including atomic and any user defined
3107 type, whether compound, opaque, enumeration, or variable length array.
3108 
3109 For even more information about a user defined type [Learn About a User
3110 Defined Type: NF\_INQ\_USER\_TYPE](#NF_005fINQ_005fUSER_005fTYPE).
3111 
3112 Usage
3113 -----
3114 
3115  
3116 
3117 
3118 INTEGER FUNCTION NF_INQ_TYPE(INTEGER NCID, INTEGER XTYPE,
3119  CHARACTER*(*) NAME, INTEGER SIZE)
3120 
3121 
3122  `NCID`
3123 : The ncid for the group containing the type (ignored for atomic
3124  types).
3125 
3126  `XTYPE`
3127 : The typeid for this type, as returned by NF\_DEF\_COMPOUND,
3128  NF\_DEF\_OPAQUE, NF\_DEF\_ENUM, NF\_DEF\_VLEN, or NF\_INQ\_VAR, or
3129  as found in netcdf.inc in the list of atomic types (NF\_CHAR,
3130  NF\_INT, etc.).
3131 
3132  `NAME`
3133 : The name of the user defined type will be copied here. It will be
3134  NF\_MAX\_NAME bytes or less. For atomic types, the type name from
3135  CDL will be given.
3136 
3137  `SIZEP`
3138 : The (in-memory) size of the type (in bytes) will be copied here.
3139  VLEN type size is the size of one vlen sturture (i.e. the sice of
3140  nc\_vlen\_t). String size is returned as the size of one C character
3141  pointer.
3142 
3143 Return Codes
3144 ------------
3145 
3146  `NF_NOERR`
3147 : No error.
3148 
3149  `NF_EBADTYPEID`
3150 : Bad typeid.
3151 
3152  `NF_ENOTNC4`
3153 : Seeking a user-defined type in a netCDF-3 file.
3154 
3155  `NF_ESTRICTNC3`
3156 : Seeking a user-defined type in a netCDF-4 file for which classic
3157  model has been turned on.
3158 
3159  `NF_EBADGRPID`
3160 : Bad group ID in ncid.
3161 
3162  `NF_EBADID`
3163 : Type ID not found.
3164 
3165  `NF_EHDFERR`
3166 : An error was reported by the HDF5 layer.
3167 
3168 Example
3169 -------
3170 
3171 This example is from the test program nf\_test/ftst\_vars3.F, and it
3172 uses all the possible inquiry functions on an enum type.
3173 
3174  
3175 
3176 
3177 C Check the enum type.
3178  retval = NF_INQ_TYPEIDS(ncid, num_types, typeids)
3179  if (retval .ne. nf_noerr) call handle_err(retval)
3180  if (num_types .ne. MAX_TYPES) stop 2
3181  retval = nf_inq_enum(ncid, typeids(1), type_name, base_type,
3182  & base_size, num_members)
3183  if (retval .ne. nf_noerr) call handle_err(retval)
3184  if (base_type .ne. NF_INT .or. num_members .ne. 2) stop 2
3185  retval = nf_inq_enum_member(ncid, typeids(1), 1, member_name,
3186  & member_value)
3187  if (retval .ne. nf_noerr) call handle_err(retval)
3188  if (member_name(1:len(one_name)) .ne. one_name) stop 2
3189 
3190 
3191 5.5 Learn About a User Defined Type: NF\_INQ\_USER\_TYPE
3192 --------------------------------------------------------
3193 
3194 Given an ncid and a typeid, get the information about a user defined
3195 type. This function will work on any user defined type, whether
3196 compound, opaque, enumeration, or variable length array.
3197 
3198 Usage
3199 -----
3200 
3201  
3202 
3203 
3204 INTEGER FUNCTION NF_INQ_USER_TYPE(INTEGER NCID, INTEGER XTYPE,
3205  CHARACTER*(*) NAME, INTEGER SIZE, INTEGER BASE_NF_TYPE,
3206  INTEGER NFIELDS, INTEGER CLASS)
3207 
3208 
3209  `NCID`
3210 : The ncid for the group containing the user defined type.
3211 
3212  `XTYPE`
3213 : The typeid for this type, as returned by NF\_DEF\_COMPOUND,
3214  NF\_DEF\_OPAQUE, NF\_DEF\_ENUM, NF\_DEF\_VLEN, or NF\_INQ\_VAR.
3215 
3216  `NAME`
3217 : The name of the user defined type will be copied here. It will be
3218  NF\_MAX\_NAME bytes or less.
3219 
3220  `SIZE`
3221 : The (in-memory) size of the user defined type will be copied here.
3222 
3223  `BASE_NF_TYPE`
3224 : The base typeid will be copied here for vlen and enum types.
3225 
3226  `NFIELDS`
3227 : The number of fields will be copied here for enum and compound
3228  types.
3229 
3230  `CLASS`
3231 : The class of the user defined type, NF\_VLEN, NF\_OPAQUE, NF\_ENUM,
3232  or NF\_COMPOUND, will be copied here.
3233 
3234 Errors
3235 ------
3236 
3237  `NF_NOERR`
3238 : No error.
3239 
3240  `NF_EBADTYPEID`
3241 : Bad typeid.
3242 
3243  `NF_EBADFIELDID`
3244 : Bad fieldid.
3245 
3246  `NF_EHDFERR`
3247 : An error was reported by the HDF5 layer.
3248 
3249 Example
3250 -------
3251 
3252 This example is from nf\_test/ftst\_types2.F.
3253 
3254  
3255 
3256 
3257 C Check the type.
3258  retval = nf_inq_user_type(ncid, typeids(1), name_in, size_in,
3259  & base_type_in, nfields_in, class_in)
3260  if (retval .ne. nf_noerr) call handle_err(retval)
3261 
3262 
3263 5.6 Compound Types Introduction
3264 -------------------------------
3265 
3266 NetCDF-4 addedpport for compound types, which allow users to
3267 construct a new type - a combination of other types, like a C struct.
3268 
3269 Compound types are notpported in classic or 64-bit offset format
3270 files.
3271 
3272 To write data in a compound type, first use nf\_def\_compound to create
3273 the type, multiple calls to nf\_insert\_compound to add to the compound
3274 type, and then write data with the appropriate nf\_put\_var1,
3275 nf\_put\_vara, nf\_put\_vars, or nf\_put\_varm call.
3276 
3277 To read data written in a compound type, you must know its structure.
3278 Use the NF\_INQ\_COMPOUND functions to learn about the compound type.
3279 
3280 In Fortran a character buffer must be used for the compound data. The
3281 user must read the data from within that buffer in the same way that the
3282 C compiler which compiled netCDF would store the structure.
3283 
3284 The use of compound types introduces challenges and portability ies
3285 for Fortran users.
3286 
3287 ### 5.6.1 Creating a Compound Type: NF\_DEF\_COMPOUND
3288 
3289 Create a compound type. Provide an ncid, a name, and a total size (in
3290 bytes) of one element of the completed compound type.
3291 
3292 After calling this function, fill out the type with repeated calls to
3293 NF\_INSERT\_COMPOUND (see [Inserting a Field into a Compound
3294 Type: NF\_INSERT\_COMPOUND](#NF_005fINSERT_005fCOMPOUND)). Call
3295 NF\_INSERT\_COMPOUND once for each field you wish to insert into the
3296 compound type.
3297 
3298 Note that there does not seem to be a way to readch types into
3299 structures in Fortran 90 (and there are no structures in Fortran 77).
3300 
3301 Fortran users may use character buffers to read and write compound
3302 types.
3303 
3304 Usage
3305 -----
3306 
3307  
3308 
3309 
3310 INTEGER FUNCTION NF_DEF_COMPOUND(INTEGER NCID, INTEGER SIZE,
3311  CHARACTER*(*) NAME, INTEGER TYPEIDP)
3312 
3313 
3314  `NCID`
3315 : The groupid where this compound type will be created.
3316 
3317  `SIZE`
3318 : The size, in bytes, of the compound type.
3319 
3320  `NAME`
3321 : The name of the new compound type.
3322 
3323  `TYPEIDP`
3324 : The typeid of the new type will be placed here.
3325 
3326 Errors
3327 ------
3328 
3329  `NF_NOERR`
3330 : No error.
3331 
3332  `NF_EBADID`
3333 : Bad group id.
3334 
3335  `NF_ENAMEINUSE`
3336 : That name is in use. Compound type names must be unique in the data
3337  file.
3338 
3339  `NF_EMAXNAME`
3340 : Name exceeds max length NF\_MAX\_NAME.
3341 
3342  `NF_EBADNAME`
3343 : Name contains illegal characters.
3344 
3345  `NF_ENOTNC4`
3346 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
3347  operations can only be performed on files defined with a create mode
3348  which includes flag NF\_NETCDF4. (see
3349  [NF\_OPEN](#NF_005fOPEN)).
3350 
3351  `NF_ESTRICTNC3`
3352 : This file was created with the strict netcdf-3 flag, therefore
3353  netcdf-4 operations are not allowed. (see
3354  [NF\_OPEN](#NF_005fOPEN)).
3355 
3356  `NF_EHDFERR`
3357 : An error was reported by the HDF5 layer.
3358 
3359  `NF_EPERM`
3360 : Attempt to write to a read-only file.
3361 
3362  `NF_ENOTINDEFINE`
3363 : Not in define mode.
3364 
3365 Example
3366 -------
3367 
3368 This example is from nf\_test/ftst\_types2.F.
3369 
3370  
3371 
3372 
3373 C Define a compound type.
3374  retval = nf_def_compound(ncid, cmp_size, type_name,
3375  & cmp_typeid)
3376  if (retval .ne. nf_noerr) call handle_err(retval)
3377 
3378 
3379 ### 5.6.2 Inserting a Field into a Compound Type: NF\_INSERT\_COMPOUND
3380 
3381 Insert a named field into a compound type.
3382 
3383 Usage
3384 -----
3385 
3386  
3387 
3388 
3389 INTEGER FUNTION NF_INSERT_COMPOUND(INTEGER TYPEID, CHARACTER*(*) NAME, INTEGER OFFSET,
3390  INTEGER FIELD_TYPEID)
3391 
3392 
3393  `TYPEID`
3394 : The typeid for this compound type, as returned by NF\_DEF\_COMPOUND,
3395  or NF\_INQ\_VAR.
3396 
3397  `NAME`
3398 : The name of the new field.
3399 
3400  `OFFSET`
3401 : Offset in byte from the beginning of the compound type for this
3402  field.
3403 
3404  `FIELD_TYPEID`
3405 : The type of the field to be inserted.
3406 
3407 Errors
3408 ------
3409 
3410  `NF_NOERR`
3411 : No error.
3412 
3413  `NF_EBADID`
3414 : Bad group id.
3415 
3416  `NF_ENAMEINUSE`
3417 : That name is in use. Field names must be unique within a compound
3418  type.
3419 
3420  `NF_EMAXNAME`
3421 : Name exceed max length NF\_MAX\_NAME.
3422 
3423  `NF_EBADNAME`
3424 : Name contains illegal characters.
3425 
3426  `NF_ENOTNC4`
3427 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
3428  operations can only be performed on files defined with a create mode
3429  which includes flag NF\_NETCDF4. (see
3430  [NF\_OPEN](#NF_005fOPEN)).
3431 
3432  `NF_ESTRICTNC3`
3433 : This file was created with the strict netcdf-3 flag, therefore
3434  netcdf-4 operations are not allowed. (see
3435  [NF\_OPEN](#NF_005fOPEN)).
3436 
3437  `NF_EHDFERR`
3438 : An error was reported by the HDF5 layer.
3439 
3440  `NF_ENOTINDEFINE`
3441 : Not in define mode.
3442 
3443 Example
3444 -------
3445 
3446 This example is from nf\_test/ftst\_types.F.
3447 
3448  
3449 
3450 
3451 C Define a compound type.
3452  retval = nf_def_compound(ncid, WIND_T_SIZE, type_name,
3453  & wind_typeid)
3454  if (retval .ne. nf_noerr) call handle_err(retval)
3455  retval = nf_insert_compound(ncid, wind_typeid, u_name, 0, NF_INT)
3456  if (retval .ne. nf_noerr) call handle_err(retval)
3457  retval = nf_insert_compound(ncid, wind_typeid, v_name, 4, NF_INT)
3458  if (retval .ne. nf_noerr) call handle_err(retval)
3459 
3460 
3461 
3462 ### 5.6.3 Inserting an Array Field into a Compound Type: NF\_INSERT\_ARRAY\_COMPOUND
3463 
3464 Insert a named array field into a compound type.
3465 
3466 Usage
3467 -----
3468 
3469  
3470 
3471 
3472 INTEGER FUNCTION NF_INSERT_ARRAY_COMPOUND(INTEGER NCID, INTEGER XTYPE,
3473  CHARACTER*(*) NAME, INTEGER OFFSET, INTEGER FIELD_TYPEID,
3474  INTEGER NDIMS, INTEGER DIM_SIZES)
3475 
3476 
3477  `NCID`
3478 : The ID of the file that contains the array type and the compound
3479  type.
3480 
3481  `XTYPE`
3482 : The typeid for this compound type, as returned by nf\_def\_compound,
3483  or nf\_inq\_var.
3484 
3485  `NAME`
3486 : The name of the new field.
3487 
3488  `OFFSET`
3489 : Offset in byte from the beginning of the compound type for this
3490  field.
3491 
3492  `FIELD_TYPEID`
3493 : The base type of the array to be inserted.
3494 
3495  `NDIMS`
3496 : The number of dimensions for the array to be inserted.
3497 
3498  `DIM_SIZES`
3499 : An array containing the sizes of each dimension.
3500 
3501 Errors
3502 ------
3503 
3504  `NF_NOERR`
3505 : No error.
3506 
3507  `NF_EBADID`
3508 : Bad group id.
3509 
3510  `NF_ENAMEINUSE`
3511 : That name is in use. Field names must be unique within a compound
3512  type.
3513 
3514  `NF_EMAXNAME`
3515 : Name exceed max length NF\_MAX\_NAME.
3516 
3517  `NF_EBADNAME`
3518 : Name contains illegal characters.
3519 
3520  `NF_ENOTNC4`
3521 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
3522  operations can only be performed on files defined with a create mode
3523  which includes flag NF\_NETCDF4. (see
3524  [NF\_OPEN](#NF_005fOPEN)).
3525 
3526  `NF_ESTRICTNC3`
3527 : This file was created with the strict netcdf-3 flag, therefore
3528  netcdf-4 operations are not allowed. (see
3529  [NF\_OPEN](#NF_005fOPEN)).
3530 
3531  `NF_EHDFERR`
3532 : An error was reported by the HDF5 layer.
3533 
3534  `NF_ENOTINDEFINE`
3535 : Not in define mode.
3536 
3537  `NF_ETYPEDEFINED`
3538 : Attempt to change type that has already been committed. The first
3539  time the file leaves define mode, all defined types are committed,
3540  and can’t be changed. If you wish to add an array to a compound
3541  type, you must do so before the compound type is committed.
3542 
3543 Example
3544 -------
3545 
3546 This example is from nf\_test/ftst\_types2.F.
3547 
3548  
3549 
3550 
3551 C Define a compound type.
3552  retval = nf_def_compound(ncid, cmp_size, type_name,
3553  & cmp_typeid)
3554  if (retval .ne. nf_noerr) call handle_err(retval)
3555 
3556 C Include an array.
3557  dim_sizes(1) = NX
3558  dim_sizes(2) = NY
3559  retval = nf_insert_array_compound(ncid, cmp_typeid, ary_name, 0,
3560  & NF_INT, NDIMS, dim_sizes)
3561  if (retval .ne. nf_noerr) call handle_err(retval)
3562 
3563 
3564 ### 5.6.4 Learn About a Compound Type: NF\_INQ\_COMPOUND
3565 
3566 Get the number of fields, length in bytes, and name of a compound type.
3567 
3568 In addtion to the NF\_INQ\_COMPOUND function, three additional functions
3569 are provided which get only the name, size, and number of fields.
3570 
3571 Usage
3572 -----
3573 
3574  
3575 
3576 
3577 INTEGER FUNCTION NF_INQ_COMPOUND(INTEGER NCID, INTEGER XTYPE,
3578  CHARACTER*(*) NAME, INTEGER SIZEP, INTEGER NFIELDSP)
3579 
3580 INTEGER FUNCTION NF_INQ_COMPOUND_NAME(INTEGER NCID, INTEGER XTYPE,
3581  CHARACTER*(*) NAME)
3582 
3583 INTEGER FUNCTION NF_INQ_COMPOUND_SIZE(INTEGER NCID, INTEGER XTYPE,
3584  INTEGER SIZEP)
3585 
3586 INTEGER FUNCTION NF_INQ_COMPOUND_NFIELDS(INTEGER NCID, INTEGER XTYPE,
3587  INTEGER NFIELDSP)
3588 
3589 
3590  `NCID`
3591 : The ID of any group in the file that contains the compound type.
3592 
3593  `XTYPE`
3594 : The typeid for this compound type, as returned by NF\_DEF\_COMPOUND,
3595  or NF\_INQ\_VAR.
3596 
3597  `NAME`
3598 : Character array which will get the name of the compound type. It
3599  will have a maximum length of NF\_MAX\_NAME.
3600 
3601  `SIZEP`
3602 : The size of the compound type in bytes will be put here.
3603 
3604  `NFIELDSP`
3605 : The number of fields in the compound type will be placed here.
3606 
3607 Return Codes
3608 ------------
3609 
3610  `NF_NOERR`
3611 : No error.
3612 
3613  `NF_EBADID`
3614 : Couldn’t find this ncid.
3615 
3616  `NF_ENOTNC4`
3617 : Not a netCDF-4/HDF5 file.
3618 
3619  `NF_ESTRICTNC3`
3620 : A netCDF-4/HDF5 file, but with CLASSIC\_MODEL. No user defined types
3621  are allowed in the classic model.
3622 
3623  `NF_EBADTYPE`
3624 : This type not a compound type.
3625 
3626  `NF_EBADTYPEID`
3627 : Bad type id.
3628 
3629  `NF_EHDFERR`
3630 : An error was reported by the HDF5 layer.
3631 
3632 Example
3633 -------
3634 
3635 This example is from nf\_test/ftst\_types.F.
3636 
3637  
3638 
3639 
3640 C Check it differently.
3641  retval = nf_inq_compound(ncid, typeids(1), name_in, size_in,
3642  & nfields_in)
3643  if (retval .ne. nf_noerr) call handle_err(retval)
3644  if (name_in(1:len(type_name)) .ne. type_name .or.
3645  & size_in .ne. WIND_T_SIZE .or. nfields_in .ne. 2) stop 2
3646 
3647 C Check it one piece at a time.
3648  retval = nf_inq_compound_nfields(ncid, typeids(1), nfields_in)
3649  if (retval .ne. nf_noerr) call handle_err(retval)
3650  if (nfields_in .ne. 2) stop 2
3651  retval = nf_inq_compound_size(ncid, typeids(1), size_in)
3652  if (retval .ne. nf_noerr) call handle_err(retval)
3653  if (size_in .ne. WIND_T_SIZE) stop 2
3654  retval = nf_inq_compound_name(ncid, typeids(1), name_in)
3655  if (retval .ne. nf_noerr) call handle_err(retval)
3656  if (name_in(1:len(type_name)) .ne. type_name) stop 2
3657 
3658 
3659 ### 5.6.5 Learn About a Field of a Compound Type: NF\_INQ\_COMPOUND\_FIELD
3660 
3661 Get information about one of the fields of a compound type.
3662 
3663 Usage
3664 -----
3665 
3666  
3667 
3668 
3669 INTEGER FUNCTION NF_INQ_COMPOUND_FIELD(INTEGER NCID, INTEGER XTYPE,
3670  INTEGER FIELDID, CHARACTER*(*) NAME, INTEGER OFFSETP,
3671  INTEGER FIELD_TYPEIDP, INTEGER NDIMSP, INTEGER DIM_SIZESP)
3672 
3673 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDNAME(INTEGER TYPEID,
3674  INTEGER FIELDID, CHARACTER*(*) NAME)
3675 
3676 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDINDEX(INTEGER TYPEID,
3677  CHARACTER*(*) NAME, INTEGER FIELDIDP)
3678 
3679 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDOFFSET(INTEGER TYPEID,
3680  INTEGER FIELDID, INTEGER OFFSETP)
3681 
3682 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDTYPE(INTEGER TYPEID,
3683  INTEGER FIELDID, INTEGER FIELD_TYPEIDP)
3684 
3685 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDNDIMS(INTEGER NCID,
3686  INTEGER XTYPE, INTEGER FIELDID, INTEGER NDIMSP)
3687 
3688 INTEGER FUNCTION NF_INQ_COMPOUND_FIELDDIM_SIZES(INTEGER NCID,
3689  INTEGER XTYPE, INTEGER FIELDID, INTEGER DIM_SIZES)
3690 
3691 
3692  `NCID`
3693 : The groupid where this compound type exists.
3694 
3695  `XTYPE`
3696 : The typeid for this compound type, as returned by NF\_DEF\_COMPOUND,
3697  or NF\_INQ\_VAR.
3698 
3699  `FIELDID`
3700 : A one-based index number specifying a field in the compound type.
3701 
3702  `NAME`
3703 : A character array which will get the name of the field. The name
3704  will be NF\_MAX\_NAME characters, at most.
3705 
3706  `OFFSETP`
3707 : An integer which will get the offset of the field.
3708 
3709  `FIELD_TYPEID`
3710 : An integer which will get the typeid of the field.
3711 
3712  `NDIMSP`
3713 : An integer which will get the number of dimensions of the field.
3714 
3715  `DIM_SIZESP`
3716 : An integer array which will get the dimension sizes of the field.
3717 
3718 Errors
3719 ------
3720 
3721  `NF_NOERR`
3722 : No error.
3723 
3724  `NF_EBADTYPEID`
3725 : Bad type id.
3726 
3727  `NF_EHDFERR`
3728 : An error was reported by the HDF5 layer.
3729 
3730 Example
3731 -------
3732 
3733 This example is from nf\_test/fst\_types.F.
3734 
3735  
3736 
3737 
3738 C Check the first field of the compound type.
3739  retval = nf_inq_compound_field(ncid, typeids(1), 1, name_in,
3740  & offset_in, field_typeid_in, ndims_in, dim_sizes_in)
3741  if (retval .ne. nf_noerr) call handle_err(retval)
3742  if (name_in(1:len(u_name)) .ne. u_name .or. offset_in .ne. 0 .or.
3743  & field_typeid_in .ne. NF_INT .or. ndims_in .ne. 0) stop 2
3744  retval = nf_inq_compound_fieldname(ncid, typeids(1), 1, name_in)
3745  if (retval .ne. nf_noerr) call handle_err(retval)
3746  if (name_in(1:len(u_name)) .ne. u_name) stop 2
3747  retval = nf_inq_compound_fieldoffset(ncid, typeids(1), 1,
3748  & offset_in)
3749  if (retval .ne. nf_noerr) call handle_err(retval)
3750  if (offset_in .ne. 0) stop 2
3751  retval = nf_inq_compound_fieldtype(ncid, typeids(1), 1,
3752  & field_typeid_in)
3753  if (retval .ne. nf_noerr) call handle_err(retval)
3754  if (field_typeid_in .ne. NF_INT) stop 2
3755  retval = nf_inq_compound_fieldndims(ncid, typeids(1), 1,
3756  & ndims_in)
3757  if (retval .ne. nf_noerr) call handle_err(retval)
3758  if (ndims_in .ne. 0) stop 2
3759 
3760 
3761 5.7 Variable Length Array Introduction
3762 --------------------------------------
3763 
3764 NetCDF-4 addedpport for a variable length array type. This is not
3765 supported in classic or 64-bit offset files, or in netCDF-4 files which
3766 were created with the NF\_CLASSIC\_MODEL flag.
3767 
3768 A variable length array is represented in C as a structure from HDF5,
3769 the nf\_vlen\_t structure. It contains a len member, which contains the
3770 length of that array, and a pointer to the array.
3771 
3772 So an array of VLEN in C is an array of nc\_vlen\_t structures. The only
3773 way to handle this in Fortran is with a character buffer sized correctly
3774 for the platform.
3775 
3776 The extra access functions NF\_GET\_VLEN\_ELEMENT and
3777 NF\_PUT\_VLEN\_ELEMENT to get and put one VLEN element. (That is, one
3778 array of variable length.) When calling the put, the data are not copied
3779 from the source. When calling the get the data are copied from VLEN
3780 allocated memory, which must still be freed (see below).
3781 
3782 VLEN arrays are handled differently with respect to allocation of
3783 memory. Generally, when reading data, it is up to the user to malloc
3784 (andbsequently free) the memory needed to hold the data. It is up to
3785 the user to ere that enough memory is allocated.
3786 
3787 With VLENs, this is impossible. The user cannot know the size of an
3788 array of VLEN until after reading the array. Therefore when reading VLEN
3789 arrays, the netCDF library will allocate the memory for the data within
3790 each VLEN.
3791 
3792 It is up to the user, however, to eventually free this memory. This is
3793 not just a matter of one call to free, with the pointer to the array of
3794 VLENs; each VLEN contains a pointer which must be freed.
3795 
3796 Compression is permitted but may not be effective for VLEN data, because
3797 the compression is applied to the nc\_vlen\_t structures, rather than
3798 the actual data.
3799 
3800 ### 5.7.1 Define a Variable Length Array (VLEN): NF\_DEF\_VLEN
3801 
3802 Use this function to define a variable length array type.
3803 
3804 Usage
3805 -----
3806 
3807  
3808 
3809 
3810 INTEGER FUNCTION NF_DEF_VLEN(INTEGER NCID, CHARACTER*(*) NAME,
3811  INTEGER BASE_TYPEID, INTEGER XTYPEP)
3812 
3813 
3814  `NCID`
3815 : The ncid of the file to create the VLEN type in.
3816 
3817  `NAME`
3818 : A name for the VLEN type.
3819 
3820  `BASE_TYPEID`
3821 : The typeid of the base type of the VLEN. For example, for a VLEN of
3822  shorts, the base type is NF\_SHORT. This can be a user defined type.
3823 
3824  `XTYPEP`
3825 : The typeid of the new VLEN type will be set here.
3826 
3827 Errors
3828 ------
3829 
3830  `NF_NOERR`
3831 : No error.
3832 
3833  `NF_EMAXNAME`
3834 : NF\_MAX\_NAME exceeded.
3835 
3836  `NF_ENAMEINUSE`
3837 : Name is already in use.
3838 
3839  `NF_EBADNAME`
3840 : Attribute or variable name contains illegal characters.
3841 
3842  `NF_EBADID`
3843 : ncid invalid.
3844 
3845  `NF_EBADGRPID`
3846 : Group ID part of ncid was invalid.
3847 
3848  `NF_EINVAL`
3849 : Size is invalid.
3850 
3851  `NF_ENOMEM`
3852 : Out of memory.
3853 
3854 Example
3855 -------
3856 
3857 This example is from nf\_test/ftst\_vars4.F.
3858 
3859  
3860 
3861 
3862 C Create the vlen type.
3863  retval = nf_def_vlen(ncid, vlen_type_name, nf_int, vlen_typeid)
3864  if (retval .ne. nf_noerr) call handle_err(retval)
3865 
3866 
3867 ### 5.7.2 Learning about a Variable Length Array (VLEN) Type: NF\_INQ\_VLEN
3868 
3869 Use this type to learn about a vlen.
3870 
3871 Usage
3872 -----
3873 
3874  
3875 
3876 
3877 INTEGER FUNCTION NF_INQ_VLEN(INTEGER NCID, INTEGER XTYPE,
3878  CHARACTER*(*) NAME, INTEGER DATUM_SIZEP, INTEGER
3879  BASE_NF_TYPEP)
3880 
3881 
3882  `NCID`
3883 : The ncid of the file that contains the VLEN type.
3884 
3885  `XTYPE`
3886 : The type of the VLEN to inquire about.
3887 
3888  `NAME`
3889 : The name of the VLEN type. The name will be NF\_MAX\_NAME characters
3890  or less.
3891 
3892  `DATUM_SIZEP`
3893 : A pointer to a size\_t, this will get the size of one element of
3894  this vlen.
3895 
3896  `BASE_NF_TYPEP`
3897 : An integer that will get the type of the VLEN base type. (In other
3898  words, what type is this a VLEN of?)
3899 
3900 Errors
3901 ------
3902 
3903  `NF_NOERR`
3904 : No error.
3905 
3906  `NF_EBADTYPE`
3907 : Can’t find the typeid.
3908 
3909  `NF_EBADID`
3910 : ncid invalid.
3911 
3912  `NF_EBADGRPID`
3913 : Group ID part of ncid was invalid.
3914 
3915 Example
3916 -------
3917 
3918 This example is from nf\_test/ftst\_vars4.F.
3919 
3920  
3921 
3922 
3923 C Use nf_inq_vlen and makere we get the same answers as we did
3924 C with nf_inq_user_type.
3925  retval = nf_inq_vlen(ncid, typeids(1), type_name, base_size,
3926  & base_type)
3927  if (retval .ne. nf_noerr) call handle_err(retval)
3928 
3929 
3930 ### 5.7.3 Releasing Memory for a Variable Length Array (VLEN) Type: NF\_FREE\_VLEN
3931 
3932 When a VLEN is read into user memory from the file, the HDF5 library
3933 performs memory allocations for each of the variable length arrays
3934 contained within the VLEN structure. This memory must be freed by the
3935 user to avoid memory leaks.
3936 
3937 This violates the normal netCDF expectation that the user is responsible
3938 for all memory allocation. But, with VLEN arrays, the underlying HDF5
3939 library allocates the memory for the user, and the user is responsible
3940 for deallocating that memory.
3941 
3942 Usage
3943 -----
3944 
3945  
3946 
3947 
3948 INTEGER FUNCTION NF_FREE_VLEN(CHARACTER VL);
3949 
3950 
3951  `VL`
3952 : The variable length array structure which is to be freed.
3953 
3954 Errors
3955 ------
3956 
3957  `NF_NOERR`
3958 : No error.
3959 
3960  `NF_EBADTYPE`
3961 : Can’t find the typeid.
3962 
3963 Example
3964 -------
3965 
3966 ### 5.7.4 Set a Variable Length Array with NF\_PUT\_VLEN\_ELEMENT
3967 
3968 Use this to set the element of the (potentially) n-dimensional array of
3969 VLEN. That is, this sets the data in one variable length array.
3970 
3971 Usage
3972 -----
3973 
3974  
3975 
3976 
3977 INTEGER FUNCTION NF_PUT_VLEN_ELEMENT(INTEGER NCID, INTEGER XTYPE,
3978  CHARACTER*(*) VLEN_ELEMENT, INTEGER LEN, DATA)
3979 
3980 
3981  `NCID`
3982 : The ncid of the file that contains the VLEN type.
3983 
3984  `XTYPE`
3985 : The type of the VLEN.
3986 
3987  `VLEN_ELEMENT`
3988 : The VLEN element to be set.
3989 
3990  `LEN`
3991 : The number of entries in this array.
3992 
3993  `DATA`
3994 : The data to be stored. Must match the base type of this VLEN.
3995 
3996 Errors
3997 ------
3998 
3999  `NF_NOERR`
4000 : No error.
4001 
4002  `NF_EBADTYPE`
4003 : Can’t find the typeid.
4004 
4005  `NF_EBADID`
4006 : ncid invalid.
4007 
4008  `NF_EBADGRPID`
4009 : Group ID part of ncid was invalid.
4010 
4011 Example
4012 -------
4013 
4014 This example is from nf\_test/ftst\_vars4.F.
4015 
4016  
4017 
4018 
4019 C Set up the vlen with this helper function, since F77 can't deal
4020 C with pointers.
4021  retval = nf_put_vlen_element(ncid, vlen_typeid, vlen,
4022  & vlen_len, data1)
4023  if (retval .ne. nf_noerr) call handle_err(retval)
4024 
4025 
4026 ### 5.7.5 Set a Variable Length Array with NF\_GET\_VLEN\_ELEMENT
4027 
4028 Use this to set the element of the (potentially) n-dimensional array of
4029 VLEN. That is, this sets the data in one variable length array.
4030 
4031 Usage
4032 -----
4033 
4034  
4035 
4036 
4037 INTEGER FUNCTION NF_GET_VLEN_ELEMENT(INTEGER NCID, INTEGER XTYPE,
4038  CHARACTER*(*) VLEN_ELEMENT, INTEGER LEN, DATA)
4039 
4040 
4041  `NCID`
4042 : The ncid of the file that contains the VLEN type.
4043 
4044  `XTYPE`
4045 : The type of the VLEN.
4046 
4047  `VLEN_ELEMENT`
4048 : The VLEN element to be set.
4049 
4050  `LEN`
4051 : This will be set to the number of entries in this array.
4052 
4053  `DATA`
4054 : The data will be copied here. Sufficient storage must be available
4055  or bad things will happen to you.
4056 
4057 Errors
4058 ------
4059 
4060  `NF_NOERR`
4061 : No error.
4062 
4063  `NF_EBADTYPE`
4064 : Can’t find the typeid.
4065 
4066  `NF_EBADID`
4067 : ncid invalid.
4068 
4069  `NF_EBADGRPID`
4070 : Group ID part of ncid was invalid.
4071 
4072 Example
4073 -------
4074 
4075 This example is from nf\_test/ftst\_vars4.F.
4076 
4077  
4078 
4079 
4080 C Read the vlen attribute.
4081  retval = nf_get_att(ncid, NF_GLOBAL, 'att1', vlen_in)
4082  if (retval .ne. nf_noerr) call handle_err(retval)
4083 
4084 C Get the data from the vlen we just read.
4085  retval = nf_get_vlen_element(ncid, vlen_typeid, vlen_in,
4086  & vlen_len_in, data1_in)
4087  if (retval .ne. nf_noerr) call handle_err(retval)
4088 
4089 
4090 5.8 Opaque Type Introduction
4091 ----------------------------
4092 
4093 NetCDF-4 addedpport for the opaque type. This is notpported in
4094 classic or 64-bit offset files.
4095 
4096 The opaque type is a type which is a collection of objects of a known
4097 size. (And each object is the same size). Nothing is known to netCDF
4098 about the contents of these blobs of data, except their size in bytes,
4099 and the name of the type.
4100 
4101 To use an opaque type, first define it with [Creating Opaque Types:
4102 NF\_DEF\_OPAQUE](#NF_005fDEF_005fOPAQUE). If encountering an enum type
4103 in a new data file, use [Learn About an Opaque Type:
4104 NF\_INQ\_OPAQUE](#NF_005fINQ_005fOPAQUE) to learn its name and size.
4105 
4106 ### 5.8.1 Creating Opaque Types: NF\_DEF\_OPAQUE
4107 
4108 Create an opaque type. Provide a size and a name.
4109 
4110 Usage
4111 -----
4112 
4113  
4114 
4115 
4116 INTEGER FUNCTION NF_DEF_OPAQUE(INTEGER NCID, INTEGER SIZE,
4117  CHARACTER*(*) NAME, INTEGER TYPEIDP)
4118 
4119 
4120  `NCID`
4121 : The groupid where the type will be created. The type may be used
4122  anywhere in the file, no matter what group it is in.
4123 
4124  `SIZE`
4125 : The size of each opaque object.
4126 
4127  `NAME`
4128 : The name for this type. Must be shorter than NF\_MAX\_NAME.
4129 
4130  `TYPEIDP`
4131 : Pointer where the new typeid for this type is returned. Use this
4132  typeid when defining variables of this type with [Create a Variable:
4133  `NF_DEF_VAR`](#NF_005fDEF_005fVAR).
4134 
4135 Errors
4136 ------
4137 
4138  `NF_NOERR`
4139 : No error.
4140 
4141  `NF_EBADTYPEID`
4142 : Bad typeid.
4143 
4144  `NF_EBADFIELDID`
4145 : Bad fieldid.
4146 
4147  `NF_EHDFERR`
4148 : An error was reported by the HDF5 layer.
4149 
4150 Example
4151 -------
4152 
4153 This example is from nf\_test/ftst\_vars3.F.
4154 
4155  
4156 
4157 
4158 C Create the opaque type.
4159  retval = nf_def_opaque(ncid, opaque_size, opaque_type_name,
4160  & opaque_typeid)
4161  if (retval .ne. nf_noerr) call handle_err(retval)
4162 
4163 
4164 ### 5.8.2 Learn About an Opaque Type: NF\_INQ\_OPAQUE
4165 
4166 Given a typeid, get the information about an opaque type.
4167 
4168 Usage
4169 -----
4170 
4171  
4172 
4173 
4174 INTEGER FUNCTION NF_INQ_OPAQUE(INTEGER NCID, INTEGER XTYPE,
4175  CHARACTER*(*) NAME, INTEGER SIZEP)
4176 
4177 
4178  `NCID`
4179 : The ncid for the group containing the opaque type.
4180 
4181  `XTYPE`
4182 : The typeid for this opaque type, as returned by NF\_DEF\_COMPOUND,
4183  or NF\_INQ\_VAR.
4184 
4185  `NAME`
4186 : The name of the opaque type will be copied here. It will be
4187  NF\_MAX\_NAME bytes or less.
4188 
4189  `SIZEP`
4190 : The size of the opaque type will be copied here.
4191 
4192 Errors
4193 ------
4194 
4195  `NF_NOERR`
4196 : No error.
4197 
4198  `NF_EBADTYPEID`
4199 : Bad typeid.
4200 
4201  `NF_EBADFIELDID`
4202 : Bad fieldid.
4203 
4204  `NF_EHDFERR`
4205 : An error was reported by the HDF5 layer.
4206 
4207 Example
4208 -------
4209 
4210 This example is from nf\_test/ftst\_vars3.F.
4211 
4212  
4213 
4214 
4215 C Use nf_inq_opaque and makere we get the same answers as we did
4216 C with nf_inq_user_type.
4217  retval = nf_inq_opaque(ncid, typeids(2), type_name, base_size)
4218  if (retval .ne. nf_noerr) call handle_err(retval)
4219 
4220 
4221 5.9 Enum Type Introduction
4222 --------------------------
4223 
4224 NetCDF-4 addedpport for the enum type. This is notpported in
4225 classic or 64-bit offset files.
4226 
4227 ### 5.9.1 Creating a Enum Type: NF\_DEF\_ENUM
4228 
4229 Create an enum type. Provide an ncid, a name, and a base integer type.
4230 
4231 After calling this function, fill out the type with repeated calls to
4232 NF\_INSERT\_ENUM (see [Inserting a Field into a Enum Type:
4233 NF\_INSERT\_ENUM](#NF_005fINSERT_005fENUM)). Call NF\_INSERT\_ENUM once
4234 for each value you wish to make part of the enumeration.
4235 
4236 Usage
4237 -----
4238 
4239  
4240 
4241 
4242 INTEGER FUNCTION NF_DEF_ENUM(INTEGER NCID, INTEGER BASE_TYPEID,
4243  CHARACTER*(*) NAME, INTEGER TYPEIDP)
4244 
4245 
4246  `NCID`
4247 : The groupid where this compound type will be created.
4248 
4249  `BASE_TYPEID`
4250 : The base integer type for this enum. Must be one of: NF\_BYTE,
4251  NF\_UBYTE, NF\_SHORT, NF\_USHORT, NF\_INT, NF\_UINT, NF\_INT64,
4252  NF\_UINT64.
4253 
4254  `NAME`
4255 : The name of the new enum type.
4256 
4257  `TYPEIDP`
4258 : The typeid of the new type will be placed here.
4259 
4260 Errors
4261 ------
4262 
4263  `NF_NOERR`
4264 : No error.
4265 
4266  `NF_EBADID`
4267 : Bad group id.
4268 
4269  `NF_ENAMEINUSE`
4270 : That name is in use. Compound type names must be unique in the data
4271  file.
4272 
4273  `NF_EMAXNAME`
4274 : Name exceeds max length NF\_MAX\_NAME.
4275 
4276  `NF_EBADNAME`
4277 : Name contains illegal characters.
4278 
4279  `NF_ENOTNC4`
4280 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
4281  operations can only be performed on files defined with a create mode
4282  which includes flag NF\_NETCDF4. (see
4283  [NF\_OPEN](#NF_005fOPEN)).
4284 
4285  `NF_ESTRICTNC3`
4286 : This file was created with the strict netcdf-3 flag, therefore
4287  netcdf-4 operations are not allowed. (see
4288  [NF\_OPEN](#NF_005fOPEN)).
4289 
4290  `NF_EHDFERR`
4291 : An error was reported by the HDF5 layer.
4292 
4293  `NF_EPERM`
4294 : Attempt to write to a read-only file.
4295 
4296  `NF_ENOTINDEFINE`
4297 : Not in define mode.
4298 
4299 This example is from nf\_test/ftst\_vars3.F.
4300 
4301  
4302 
4303 
4304 C Create the enum type.
4305  retval = nf_def_enum(ncid, NF_INT, enum_type_name, enum_typeid)
4306  if (retval .ne. nf_noerr) call handle_err(retval)
4307 
4308 
4309 ### 5.9.2 Inserting a Field into a Enum Type: NF\_INSERT\_ENUM
4310 
4311 Insert a named member into a enum type.
4312 
4313 Usage
4314 -----
4315 
4316  
4317 
4318 
4319 INTEGER FUNCTION NF_INSERT_ENUM(INTEGER NCID, INTEGER XTYPE,
4320  CHARACTER IDENTIFIER, INTEGER VALUE)
4321 
4322 
4323  `NCID`
4324 : The ncid of the group which contains the type.
4325 
4326  `TYPEID`
4327 : The typeid for this enum type, as returned by nf\_def\_enum, or
4328  nf\_inq\_var.
4329 
4330  `IDENTIFIER`
4331 : The identifier of the new member.
4332 
4333  `VALUE`
4334 : The value that is to be associated with this member.
4335 
4336 Errors
4337 ------
4338 
4339  `NF_NOERR`
4340 : No error.
4341 
4342  `NF_EBADID`
4343 : Bad group id.
4344 
4345  `NF_ENAMEINUSE`
4346 : That name is in use. Field names must be unique within a enum type.
4347 
4348  `NF_EMAXNAME`
4349 : Name exceed max length NF\_MAX\_NAME.
4350 
4351  `NF_EBADNAME`
4352 : Name contains illegal characters.
4353 
4354  `NF_ENOTNC4`
4355 : Attempting a netCDF-4 operation on a netCDF-3 file. NetCDF-4
4356  operations can only be performed on files defined with a create mode
4357  which includes flag NF\_NETCDF4. (see
4358  [NF\_OPEN](#NF_005fOPEN)).
4359 
4360  `NF_ESTRICTNC3`
4361 : This file was created with the strict netcdf-3 flag, therefore
4362  netcdf-4 operations are not allowed. (see
4363  [NF\_OPEN](#NF_005fOPEN)).
4364 
4365  `NF_EHDFERR`
4366 : An error was reported by the HDF5 layer.
4367 
4368  `NF_ENOTINDEFINE`
4369 : Not in define mode.
4370 
4371 Example
4372 -------
4373 
4374 This example is from nf\_test/ftst\_vars3.F.
4375 
4376  
4377 
4378 
4379  one = 1
4380  zero = 0
4381  retval = nf_insert_enum(ncid, enum_typeid, zero_name, zero)
4382  if (retval .ne. nf_noerr) call handle_err(retval)
4383  retval = nf_insert_enum(ncid, enum_typeid, one_name, one)
4384  if (retval .ne. nf_noerr) call handle_err(retval)
4385 
4386 
4387 ### 5.9.3 Learn About a Enum Type: NF\_INQ\_ENUM
4388 
4389 Get information about a user-defined enumeration type.
4390 
4391 Usage
4392 -----
4393 
4394  
4395 
4396 
4397 INTEGER FUNCTION NF_INQ_ENUM(INTEGER NCID, INTEGER XTYPE,
4398  CHARACTER*(*) NAME, INTEGER BASE_NF_TYPE, INTEGER BASE_SIZE,
4399  INTEGER NUM_MEMBERS)
4400 
4401 
4402  `NCID`
4403 : The group ID of the group which holds the enum type.
4404 
4405  `XTYPE`
4406 : The typeid for this enum type, as returned by NF\_DEF\_ENUM, or
4407  NF\_INQ\_VAR.
4408 
4409  `NAME`
4410 : Character array which will get the name. It will have a maximum
4411  length of NF\_MAX\_NAME.
4412 
4413  `BASE_NF_TYPE`
4414 : An integer which will get the base integer type of this enum.
4415 
4416  `BASE_SIZE`
4417 : An integer which will get the size (in bytes) of the base integer
4418  type of this enum.
4419 
4420  `NUM_MEMBERS`
4421 : An integer which will get the number of members defined for this
4422  enumeration type.
4423 
4424 Errors
4425 ------
4426 
4427  `NF_NOERR`
4428 : No error.
4429 
4430  `NF_EBADTYPEID`
4431 : Bad type id.
4432 
4433  `NF_EHDFERR`
4434 : An error was reported by the HDF5 layer.
4435 
4436 Example
4437 -------
4438 
4439 In this example from nf\_test/ftst\_vars3.F, an enum type is created and
4440 then examined:
4441 
4442  
4443 
4444 
4445  retval = nf_inq_enum(ncid, typeids(1), type_name, base_type,
4446  & base_size, num_members)
4447  if (retval .ne. nf_noerr) call handle_err(retval)
4448  if (base_type .ne. NF_INT .or. num_members .ne. 2) stop 2
4449 
4450 
4451 ### 5.9.4 Learn the Name of a Enum Type: nf\_inq\_enum\_member
4452 
4453 Get information about a member of an enum type.
4454 
4455 Usage
4456 -----
4457 
4458  
4459 
4460 
4461 INTEGER FUNCTION NF_INQ_ENUM_MEMBER(INTEGER NCID, INTEGER XTYPE,
4462  INTEGER IDX, CHARACTER*(*) NAME, INTEGER VALUE)
4463 
4464 
4465  `NCID`
4466 : The groupid where this enum type exists.
4467 
4468  `XTYPE`
4469 : The typeid for this enum type.
4470 
4471  `IDX`
4472 : The one-based index number for the member of interest.
4473 
4474  `NAME`
4475 : A character array which will get the name of the member. It will
4476  have a maximum length of NF\_MAX\_NAME.
4477 
4478  `VALUE`
4479 : An integer that will get the value associated with this member.
4480 
4481 Errors
4482 ------
4483 
4484  `NF_NOERR`
4485 : No error.
4486 
4487  `NF_EBADTYPEID`
4488 : Bad type id.
4489 
4490  `NF_EHDFERR`
4491 : An error was reported by the HDF5 layer.
4492 
4493 Example
4494 -------
4495 
4496 This example is from nf\_test/ftst\_vars3.F:
4497 
4498  
4499 
4500 
4501 C Check the members of the enum type.
4502  retval = nf_inq_enum_member(ncid, typeids(1), 1, member_name,
4503  & member_value)
4504  if (retval .ne. nf_noerr) call handle_err(retval)
4505  if (member_name(1:len(zero_name)) .ne. zero_name .or.
4506  & member_value .ne. 0) stop 2
4507  retval = nf_inq_enum_member(ncid, typeids(1), 2, member_name,
4508  & member_value)
4509  if (retval .ne. nf_noerr) call handle_err(retval)
4510  if (member_name(1:len(one_name)) .ne. one_name .or.
4511  & member_value .ne. 1) stop 2
4512 
4513 
4514 ### 5.9.5 Learn the Name of a Enum Type: NF\_INQ\_ENUM\_IDENT
4515 
4516 Get the name which is associated with an enum member value.
4517 
4518 This is similar to NF\_INQ\_ENUM\_MEMBER, but instead of using the index
4519 of the member, you use the value of the member.
4520 
4521 Usage
4522 -----
4523 
4524  
4525 
4526 
4527 INTEGER FUNCTION NF_INQ_ENUM_IDENT(INTEGER NCID, INTEGER XTYPE,
4528  INTEGER VALUE, CHARACTER*(*) IDENTIFIER)
4529 
4530 
4531  `NCID`
4532 : The groupid where this enum type exists.
4533 
4534  `XTYPE`
4535 : The typeid for this enum type.
4536 
4537  `VALUE`
4538 : The value for which an identifier is sought.
4539 
4540  `IDENTIFIER`
4541 : A character array that will get the identifier. It will have a
4542  maximum length of NF\_MAX\_NAME.
4543 
4544 Return Code
4545 -----------
4546 
4547  `NF_NOERR`
4548 : No error.
4549 
4550  `NF_EBADTYPEID`
4551 : Bad type id, or not an enum type.
4552 
4553  `NF_EHDFERR`
4554 : An error was reported by the HDF5 layer.
4555 
4556  `NF_EINVAL`
4557 : The value was not found in the enum.
4558 
4559 Example
4560 -------
4561 
4562 In this example from nf\_test/ftst\_vars3.F, the values for 0 and 1 are
4563 checked in an enum.
4564 
4565  
4566 
4567 
4568  retval = nf_inq_enum_ident(ncid, typeids(1), 0, member_name)
4569  if (retval .ne. nf_noerr) call handle_err(retval)
4570  if (member_name(1:len(zero_name)) .ne. zero_name) stop 2
4571  retval = nf_inq_enum_ident(ncid, typeids(1), 1, member_name)
4572  if (retval .ne. nf_noerr) call handle_err(retval)
4573  if (member_name(1:len(one_name)) .ne. one_name) stop 2
4574 
4575 
4576 6. Variables
4577 ============
4578 
4579 6.1 Variables Introduction
4580 --------------------------
4581 
4582 Variables for a netCDF dataset are defined when the dataset is created,
4583 while the netCDF dataset is in define mode. Other variables may be added
4584 later by reentering define mode. A netCDF variable has a name, a type,
4585 and a shape, which are specified when it is defined. A variable may also
4586 have values, which are established later in data mode.
4587 
4588 Ordinarily, the name, type, and shape are fixed when the variable is
4589 first defined. The name may be changed, but the type and shape of a
4590 variable cannot be changed. However, a variable defined in terms of the
4591 unlimited dimension can grow without bound in that dimension.
4592 
4593 A netCDF variable in an open netCDF dataset is referred to by a small
4594 integer called a variable ID.
4595 
4596 Variable IDs reflect the order in which variables were defined within a
4597 netCDF dataset. Variable IDs are 1, 2, 3,..., in the order in which the
4598 variables were defined. A function is available for getting the variable
4599 ID from the variable name and vice-versa.
4600 
4601 Attributes (see [Attributes](#Attributes)) may be associated with a
4602 variable to specifych properties as units.
4603 
4604 Operationspported on variables are:
4605 
4606 - Create a variable, given its name, data type, and shape.
4607 - Get a variable ID from its name.
4608 - Get a variable’s name, data type, shape, and number of attributes
4609  from its ID.
4610 - Put a data value into a variable, given variable ID, indices, and
4611  value.
4612 - Put an array of values into a variable, given variable ID, corner
4613  indices, edge lengths, and a block of values.
4614 - Put absampled or mapped array of values into a variable,
4615  given variable ID, corner indices, edge lengths, stride vector,
4616  index mapping vector, and a block of values.
4617 - Get a data value from a variable, given variable ID and indices.
4618 - Get an array of values from a variable, given variable ID, corner
4619  indices, and edge lengths.
4620 - Get absampled or mapped array of values from a variable,
4621  given variable ID, corner indices, edge lengths, stride vector, and
4622  index mapping vector.
4623 - Rename a variable.
4624 
4625 
4626 6.2 Language Types Corresponding to netCDF external data types
4627 --------------------------------------------------------------
4628 
4629 The following table gives the netCDF external data types and the
4630 corresponding type constants for defining variables in the FORTRAN
4631 interface:
4632 
4633  -------- ---------------------- ------
4634  Type FORTRAN API Mnemonic Bits
4635  byte NF\_BYTE 8
4636  char NF\_CHAR 8
4637  short NF\_SHORT 16
4638  int NF\_INT 32
4639  float NF\_FLOAT 32
4640  double NF\_DOUBLE 64
4641  -------- ---------------------- ------
4642 
4643 The first column gives the netCDF external data type, which is the same
4644 as the CDL data type. The next column gives the corresponding FORTRAN
4645 parameter for use in netCDF functions (the parameters are defined in the
4646 netCDF FORTRAN include-file netcdf.inc). The last column gives the
4647 number of bits used in the external representation of values of the
4648 corresponding type.
4649 
4650 Note that there are no netCDF types corresponding to 64-bit integers or
4651 to characters wider than 8 bits in the current version of the netCDF
4652 library.
4653 
4654 6.3 Create a Variable: `NF_DEF_VAR`
4655 -----------------------------------
4656 
4657 The function NF\_DEF\_VAR adds a new variable to an open netCDF dataset
4658 in define mode. It returns (as an argument) a variable ID, given the
4659 netCDF ID, the variable name, the variable type, the number of
4660 dimensions, and a list of the dimension IDs.
4661 
4662 Usage
4663 -----
4664 
4665  
4666 
4667 
4668 INTEGER FUNCTION NF_DEF_VAR(INTEGER NCID, CHARACTER*(*) NAME,
4669  INTEGER XTYPE, INTEGER NVDIMS,
4670  INTEGER VDIMS(*), INTEGER varid)
4671 
4672 
4673  `NCID`
4674 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
4675 
4676  `NAME`
4677 : Variable name.
4678 
4679  `XTYPE`
4680 : One of the set of predefined netCDF external data types. The type of
4681  this parameter, NF\_TYPE, is defined in the netCDF header file. The
4682  valid netCDF external data types are NF\_BYTE, NF\_CHAR, NF\_SHORT,
4683  NF\_INT, NF\_FLOAT, and NF\_DOUBLE. If the file is a NetCDF-4/HDF5
4684  file, the additional types NF\_UBYTE, NF\_USHORT, NF\_UINT,
4685  NF\_INT64, NF\_UINT64, and NF\_STRING may be used, as well as a user
4686  defined type ID.
4687 
4688  `NVDIMS`
4689 : Number of dimensions for the variable. For example, 2 specifies a
4690  matrix, 1 specifies a vector, and 0 means the variable is a scalar
4691  with no dimensions. Must not be negative or greater than the
4692  predefined constant NF\_MAX\_VAR\_DIMS.
4693 
4694  `VDIMS`
4695 : Vector of ndims dimension IDs corresponding to the variable
4696  dimensions. If the ID of the unlimited dimension is included, it
4697  must be first. This argument is ignored if ndims is 0. For expanded
4698  model netCDF4/HDF5 files, there may be any number of unlimited
4699  dimensions, and they may be used in any element of the dimids array.
4700 
4701  `varid`
4702 : Returned variable ID.
4703 
4704 Errors
4705 ------
4706 
4707 NF\_DEF\_VAR returns the value NF\_NOERR if no errors occurred.
4708 Otherwise, the returned status indicates an error. Possible causes of
4709 errors include:
4710 
4711 - The netCDF dataset is not in define mode.
4712 - The specified variable name is the name of another existing
4713  variable.
4714 - The specified type is not a valid netCDF type.
4715 - The specified number of dimensions is negative or more than the
4716  constant NF\_MAX\_VAR\_DIMS, the maximum number of dimensions
4717  permitted for a netCDF variable.
4718 - One or more of the dimension IDs in the list of dimensions is not a
4719  valid dimension ID for the netCDF dataset.
4720 - The number of variables would exceed the constant NF\_MAX\_VARS, the
4721  maximum number of variables permitted in a netCDF dataset.
4722 - The specified netCDF ID does not refer to an open netCDF dataset.
4723 
4724 Example
4725 -------
4726 
4727 Here is an example using NF\_DEF\_VAR to create a variable named rh of
4728 type double with three dimensions, time, lat, and lon in a new netCDF
4729 dataset named foo.nc:
4730 
4731  
4732 
4733 
4734 INCLUDE 'netcdf.inc'
4735  ...
4736 INTEGER STATUS, NCID
4737 INTEGER LATDIM, LONDIM, TIMDIM ! dimension IDs
4738 INTEGER RHID ! variable ID
4739 INTEGER RHDIMS(3) ! variable shape
4740  ...
4741 STATUS = NF_CREATE ('foo.nc', NF_NOCLOBBER, NCID)
4742 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
4743  ...
4744  ! define dimensions
4745 STATUS = NF_DEF_DIM(NCID, 'lat', 5, LATDIM)
4746 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
4747 STATUS = NF_DEF_DIM(NCID, 'lon', 10, LONDIM)
4748 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
4749 STATUS = NF_DEF_DIM(NCID, 'time', NF_UNLIMITED, TIMDIM)
4750 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
4751  ...
4752  ! define variable
4753 RHDIMS(1) = LONDIM
4754 RHDIMS(2) = LATDIM
4755 RHDIMS(3) = TIMDIM
4756 STATUS = NF_DEF_VAR (NCID, 'rh', NF_DOUBLE, 3, RHDIMS, RHID)
4757 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
4758 
4759 
4760 6.4 Define Chunking Parameters for a Variable: `NF_DEF_VAR_CHUNKING`
4761 --------------------------------------------------------------------
4762 
4763 The function NF\_DEF\_VAR\_CHUNKING sets the storage parameters for a
4764 variable in a netCDF-4 file. It can set the chunk sizes to get chunked
4765 storage, or it can set the contiguous flag to get contiguous storage.
4766 
4767 Variables that make use of one or more unlimited dimensions,
4768 compression, or checms must use chunking. Such variables are created
4769 with default chunk sizes of 1 for each unlimited dimension and the
4770 dimension length for other dimensions, except that if the rlting
4771 chunks are too large, the default chunk sizes for non-record dimensions
4772 are reduced.
4773 
4774 The total size of a chunk must be less than 4 GiB. That is, the product
4775 of all chunksizes and the size of the data (or the size of nc\_vlen\_t
4776 for VLEN types) must be less than 4 GiB.
4777 
4778 This function may only be called after the variable is defined, but
4779 before nc\_enddef is called. Once the chunking parameters are set for a
4780 variable, they cannot be changed. This function can be used to change
4781 the default chunking for record, compressed, or checmmed variables
4782 before nc\_enddef is called.
4783 
4784 Note that you cannot set chunking for scalar variables. Only non-scalar
4785 variables can have chunking.
4786 
4787 Usage
4788 -----
4789 
4790  
4791 
4792 
4793 NF_DEF_VAR_CHUNKING(INTEGER NCID, INTEGER VARID, INTEGER STORAGE, INTEGER CHUNKSIZES)
4794 
4795 
4796  `ncid`
4797 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
4798 
4799  `varid`
4800 : Variable ID.
4801 
4802  `storage`
4803 : If NF\_CONTIGUOUS, then contiguous storage is used for this
4804  variable. Variables with compression, shuffle filter, checms, or
4805  one or more unlimited dimensions cannot use contiguous storage. If
4806  contiguous storage is turned on, the chunksizes parameter is
4807  ignored.
4808 
4809  If NF\_CHUNKED, then chunked storage is used for this variable.
4810  Chunk sizes may be specified with the chunksizes parameter. Default
4811  sizes will be used if chunking is required and this function is not
4812  called.
4813 
4814  By default contiguous storage is used for fix-sized variables when
4815  conpression, chunking, checms, or endianness control are not
4816  used.
4817 
4818  `chunksizes`
4819 : An array of chunk sizes. The array must have the one chunksize for
4820  each dimension in the variable. If contiguous storage is used, then
4821  the chunksizes parameter is ignored.
4822 
4823 Errors
4824 ------
4825 
4826 NF\_DEF\_VAR\_CHUNKING returns the value NF\_NOERR if no errors
4827 occurred. Otherwise, the returned status indicates an error.
4828 
4829 Possible return codes include:
4830 
4831  `NF_NOERR`
4832 : No error.
4833 
4834  `NF_BADID`
4835 : Bad ncid.
4836 
4837  `NF_EINVAL`
4838 : Invalid input. This can occur when the user attempts to set
4839  contiguous storage for a variable with compression or checms, or
4840  one or more unlimited dimensions.
4841 
4842  `NF_ENOTNC4`
4843 : Not a netCDF-4 file.
4844 
4845  `NF_ENOTVAR`
4846 : Can’t find this variable.
4847 
4848  `NF_ELATEDEF`
4849 : This variable has already been thebject of a NF\_ENDDEF call. In
4850  netCDF-4 files NF\_ENDDEF will be called automatically for any data
4851  read or write. Once enddef has been called, it is impossible to set
4852  the chunking for a variable.
4853 
4854  `NF_ENOTINDEFINE`
4855 : Not in define mode. This is returned for netCDF classic or 64-bit
4856  offset files, or for netCDF-4 files, when they were been created
4857  with NF\_STRICT\_NC3 flag. (see
4858  [NF\_CREATE](#NF_005fCREATE)).
4859 
4860  `NF_ESTRICTNC3`
4861 : Trying to create a var some place other than the root group in a
4862  netCDF file with NF\_STRICT\_NC3 turned on.
4863 
4864 Example
4865 -------
4866 
4867 In this example from nf\_test/ftst\_vars.F, a file is created, two
4868 dimensions and a variable are defined, and the chunksizes of the data
4869 are set to the size of the data (that is, data will be written in one
4870 chunk).
4871 
4872  
4873 
4874 
4875 C Create the netCDF file.
4876  retval = nf_create(FILE_NAME, NF_NETCDF4, ncid)
4877  if (retval .ne. nf_noerr) call handle_err(retval)
4878 
4879 C Define the dimensions.
4880  retval = nf_def_dim(ncid, "x", NX, x_dimid)
4881  if (retval .ne. nf_noerr) call handle_err(retval)
4882  retval = nf_def_dim(ncid, "y", NY, y_dimid)
4883  if (retval .ne. nf_noerr) call handle_err(retval)
4884 
4885 C Define the variable.
4886  dimids(1) = y_dimid
4887  dimids(2) = x_dimid
4888  retval = NF_DEF_VAR(ncid, "data", NF_INT, NDIMS, dimids, varid)
4889  if (retval .ne. nf_noerr) call handle_err(retval)
4890 
4891 C Turn on chunking.
4892  chunks(1) = NY
4893  chunks(2) = NX
4894  retval = NF_DEF_VAR_chunking(ncid, varid, NF_CHUNKED, chunks)
4895  if (retval .ne. nf_noerr) call handle_err(retval)
4896 
4897 
4898 6.5 Learn About Chunking Parameters for a Variable: `NF_INQ_VAR_CHUNKING`
4899 -------------------------------------------------------------------------
4900 
4901 The function NF\_INQ\_VAR\_CHUNKING returns the chunking settings for a
4902 variable in a netCDF-4 file.
4903 
4904 Usage
4905 -----
4906 
4907  
4908 
4909 
4910 NF_INQ_VAR_CHUNKING(INTEGER NCID, INTEGER VARID, INTEGER STORAGE, INTEGER CHUNKSIZES);
4911 
4912 
4913  `NCID`
4914 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
4915 
4916  `VARID`
4917 : Variable ID.
4918 
4919  `STORAGE`
4920 : On return, set to NF\_CONTIGUOUS if this variable uses contiguous
4921  storage, NF\_CHUNKED if it uses chunked storage.
4922 
4923  `CHUNKSIZES`
4924 : An array of chunk sizes. The length of CHUNKSIZES must be the same
4925  as the number of dimensions of the variable.
4926 
4927 Errors
4928 ------
4929 
4930 NF\_INQ\_VAR\_CHUNKING returns the value NF\_NOERR if no errors
4931 occurred. Otherwise, the returned status indicates an error.
4932 
4933 Possible return codes include:
4934 
4935  `NF_NOERR`
4936 : No error.
4937 
4938  `NF_BADID`
4939 : Bad ncid.
4940 
4941  `NF_ENOTNC4`
4942 : Not a netCDF-4 file.
4943 
4944  `NF_ENOTVAR`
4945 : Can’t find this variable.
4946 
4947 Example
4948 -------
4949 
4950 In this example from nf\_test/ftst\_vars.F, a variable with chunked
4951 storage is checked to ere that the chunksizes are set to expected
4952 values.
4953 
4954  
4955 
4956 
4957 C Is everything set that ispposed to be?
4958  retval = nf_inq_var_chunking(ncid, varid, storage, chunks_in)
4959  if (retval .ne. nf_noerr) call handle_err(retval)
4960  if (storage .ne. NF_CHUNKED) stop 2
4961  if (chunks(1) .ne. chunks_in(1)) stop 2
4962  if (chunks(2) .ne. chunks_in(2)) stop 2
4963 
4964 
4965 6.6 Set HDF5 Chunk Cache for a Variable: NF\_SET\_VAR\_CHUNK\_CACHE
4966 -------------------------------------------------------------------
4967 
4968 This function changes the chunk cache settings for a variable. The
4969 change in cache size happens immediately. This is a property of the open
4970 file - it does not persist the next time you open the file.
4971 
4972 For more information, see the documentation for the H5Pset\_cache()
4973 function in the HDF5 library at the HDF5 website:
4974 [http://hdfgroup.org/HDF5/](http://hdfgroup.org/HDF5/).
4975 
4976 Usage
4977 -----
4978 
4979  
4980 
4981 
4982 NF_SET_VAR_CHUNK_CACHE(INTEGER NCID, INTEGER VARID, INTEGER SIZE, INTEGER NELEMS,
4983  INTEGER PREEMPTION);
4984 
4985 
4986  `NCID`
4987 : NetCDF ID, from a previous call to nc\_open or nc\_create.
4988 
4989  `VARID`
4990 : Variable ID.
4991 
4992  `SIZE`
4993 : The total size of the raw data chunk cache, in megabytes. This
4994  should be big enough to hold multiple chunks of data. (Note that the
4995  C API uses bytes, but the Fortran APIs uses megabytes to avoid
4996  numbers that can’t fit in 4-byte integers.)
4997 
4998  `NELEMS`
4999 : The number of chunk slots in the raw data chunk cache hash table.
5000  This should be a prime number larger than the number of chunks that
5001  will be in the cache.
5002 
5003  `PREEMPTION`
5004 : The preemption value must be between 0 and 100 inclusive and
5005  indicates the degreee to which chunks that have been fully read are
5006  favored for kicking out of the chunk cache, when needed. A value of
5007  zero means fully read chunks are treated no differently than other
5008  chunks (the preemption is strictly Least Recently Used) while a
5009  value of 100 means fully read chunks are always preempted before
5010  other chunks. (The C API uses a float between 0 and 1 for this
5011  value).
5012 
5013 Return Codes
5014 ------------
5015 
5016  `NF_NOERR`
5017 : No error.
5018 
5019  `NF_EINVAL`
5020 : Preemption must be between zero and 100 (inclusive).
5021 
5022 Example
5023 -------
5024 
5025 This example is from nf\_test/ftst\_vars2.F:
5026 
5027  
5028 
5029 
5030  include 'netcdf.inc'
5031  ...
5032 C These will be used to set the per-variable chunk cache.
5033  integer CACHE_SIZE, CACHE_NELEMS, CACHE_PREEMPTION
5034  parameter (CACHE_SIZE = 8, CACHE_NELEMS = 571)
5035  parameter (CACHE_PREEMPTION = 42)
5036 ...
5037 C Set variable caches.
5038  retval = nf_set_var_chunk_cache(ncid, varid(i), CACHE_SIZE,
5039  & CACHE_NELEMS, CACHE_PREEMPTION)
5040  if (retval .ne. nf_noerr) call handle_err(retval)
5041 
5042 
5043 6.7 Get the HDF5 Chunk Cache Settings for a variable: NF\_GET\_VAR\_CHUNK\_CACHE
5044 --------------------------------------------------------------------------------
5045 
5046 This function gets the current chunk cache settings for a variable in a
5047 netCDF-4/HDF5 file.
5048 
5049 For more information, see the documentation for the H5Pget\_cache()
5050 function in the HDF5 library at the HDF5 website:
5051 [http://hdfgroup.org/HDF5/](http://hdfgroup.org/HDF5/).
5052 
5053 Usage
5054 -----
5055 
5056  
5057 
5058 
5059 INTEGER NF_GET_VAR_CHUNK_CACHE(INTEGER NCID, INTEGER VARID, INTEGER SIZE, INTEGER NELEMS,
5060  INTEGER PREEMPTION);
5061 
5062 
5063  `ncid`
5064 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5065 
5066  `varid`
5067 : Variable ID.
5068 
5069  `sizep`
5070 : The total size of the raw data chunk cache, in megabytes, will be
5071  put here.
5072 
5073  `nelemsp`
5074 : The number of chunk slots in the raw data chunk cache hash table
5075  will be put here.
5076 
5077  `preemptionp`
5078 : The preemption will be put here. The preemtion value is between 0
5079  and 100 inclusive and indicates how much chunks that have been fully
5080  read are favored for preemption. A value of zero means fully read
5081  chunks are treated no differently than other chunks (the preemption
5082  is strictly LRU) while a value of 100 means fully read chunks are
5083  always preempted before other chunks.
5084 
5085 Return Codes
5086 ------------
5087 
5088  `NC_NOERR`
5089 : No error.
5090 
5091 Example
5092 -------
5093 
5094 This example is from nf\_test/ftst\_vars2.c:
5095 
5096  
5097 
5098 
5099  include 'netcdf.inc'
5100 ...
5101 C These will be used to set the per-variable chunk cache.
5102  integer CACHE_SIZE, CACHE_NELEMS, CACHE_PREEMPTION
5103  parameter (CACHE_SIZE = 8, CACHE_NELEMS = 571)
5104  parameter (CACHE_PREEMPTION = 42)
5105 
5106 C These will be used to check the setting of the per-variable chunk
5107 C cache.
5108  integer cache_size_in, cache_nelems_in, cache_preemption_in
5109 
5110 ...
5111  retval = nf_get_var_chunk_cache(ncid, varid(i), cache_size_in,
5112  & cache_nelems_in, cache_preemption_in)
5113  if (retval .ne. nf_noerr) call handle_err(retval)
5114  if (cache_size_in .ne. CACHE_SIZE .or. cache_nelems_in .ne.
5115  & CACHE_NELEMS .or. cache_preemption .ne. CACHE_PREEMPTION)
5116  & stop 8
5117 
5118 
5119 6.8 Define Fill Parameters for a Variable: `nf_def_var_fill`
5120 ------------------------------------------------------------
5121 
5122 The function NF\_DEF\_VAR\_FILL sets the fill parameters for a variable
5123 in a netCDF-4 file.
5124 
5125 This function must be called after the variable is defined, but before
5126 NF\_ENDDEF is called.
5127 
5128 Usage
5129 -----
5130 
5131  
5132 
5133 
5134 NF_DEF_VAR_FILL(INTEGER NCID, INTEGER VARID, INTEGER NO_FILL, FILL_VALUE);
5135 
5136 
5137  `NCID`
5138 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5139 
5140  `VARID`
5141 : Variable ID.
5142 
5143  `NO_FILL`
5144 : Set to non-zero value to set no\_fill mode on a variable. When this
5145  mode is on, fill values will not be written for the variable. This
5146  is helpful in high performance applications. For netCDF-4/HDF5 files
5147  (whether classic model or not), this may only be changed after the
5148  variable is defined, but before it is committed to disk (i.e. before
5149  the first NF\_ENDDEF after the NF\_DEF\_VAR.) For classic and 64-bit
5150  offset file, the no\_fill mode may be turned on and off at any time.
5151 
5152  `FILL_VALUE`
5153 : A value which will be used as the fill value for the variable. Must
5154  be the same type as the variable. This will be written to a
5155  \_FillValue attribute, created for this purpose. If NULL, this
5156  argument will be ignored.
5157 
5158 Return Codes
5159 ------------
5160 
5161  `NF_NOERR`
5162 : No error.
5163 
5164  `NF_BADID`
5165 : Bad ncid.
5166 
5167  `NF_ENOTNC4`
5168 : Not a netCDF-4 file.
5169 
5170  `NF_ENOTVAR`
5171 : Can’t find this variable.
5172 
5173  `NF_ELATEDEF`
5174 : This variable has already been thebject of a NF\_ENDDEF call. In
5175  netCDF-4 files NF\_ENDDEF will be called automatically for any data
5176  read or write. Once enddef has been called, it is impossible to set
5177  the fill for a variable.
5178 
5179  `NF_ENOTINDEFINE`
5180 : Not in define mode. This is returned for netCDF classic or 64-bit
5181  offset files, or for netCDF-4 files, when they were been created
5182  with NF\_STRICT\_NC3 flag. (see
5183  [NF\_CREATE](#NF_005fCREATE)).
5184 
5185  `NF_EPERM`
5186 : Attempt to create object in read-only file.
5187 
5188 Example
5189 -------
5190 
5191 6.9 Learn About Fill Parameters for a Variable: `NF_INQ_VAR_FILL`
5192 -----------------------------------------------------------------
5193 
5194 The function NF\_INQ\_VAR\_FILL returns the fill settings for a variable
5195 in a netCDF-4 file.
5196 
5197 Usage
5198 -----
5199 
5200  
5201 
5202 
5203 NF_INQ_VAR_FILL(INTEGER NCID, INTEGER VARID, INTEGER NO_FILL, FILL_VALUE)
5204 
5205 
5206  `NCID`
5207 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5208 
5209  `VARID`
5210 : Variable ID.
5211 
5212  `NO_FILL`
5213 : An integer which will get a 1 if no\_fill mode is set for this
5214  variable, and a zero if it is not set
5215 
5216  `FILL_VALUE`
5217 : This will get the fill value for this variable. This parameter will
5218  be ignored if it is NULL.
5219 
5220 Return Codes
5221 ------------
5222 
5223  `NF_NOERR`
5224 : No error.
5225 
5226  `NF_BADID`
5227 : Bad ncid.
5228 
5229  `NF_ENOTNC4`
5230 : Not a netCDF-4 file.
5231 
5232  `NF_ENOTVAR`
5233 : Can’t find this variable.
5234 
5235 Example
5236 -------
5237 
5238 6.10 Define Compression Parameters for a Variable: `NF_DEF_VAR_DEFLATE`
5239 -----------------------------------------------------------------------
5240 
5241 The function NF\_DEF\_VAR\_DEFLATE sets the deflate parameters for a
5242 variable in a netCDF-4 file.
5243 
5244 When using parallel I/O for writing data, deflate cannot be used. This
5245 is because the compression makes it impossible for the HDF5 library to
5246 exactly map the data to disk location.
5247 
5248 (Deflated data can be read with parallel I/O).
5249 
5250 NF\_DEF\_VAR\_DEFLATE must be called after the variable is defined, but
5251 before NF\_ENDDEF is called.
5252 
5253 Usage
5254 -----
5255 
5256  
5257 
5258 
5259 NF_DEF_VAR_DEFLATE(INTEGER NCID, INTEGER VARID, INTEGER SHUFFLE, INTEGER DEFLATE,
5260  INTEGER DEFLATE_LEVEL);
5261 
5262 
5263  `NCID`
5264 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5265 
5266  `VARID`
5267 : Variable ID.
5268 
5269  `SHUFFLE`
5270 : If non-zero, turn on the shuffle filter.
5271 
5272  `DEFLATE`
5273 : If non-zero, turn on the deflate filter at the level specified by
5274  the deflate\_level parameter.
5275 
5276  `DEFLATE_LEVEL`
5277 : Must be between 0 (no deflate, the default) and 9 (slowest, but
5278  “best” deflate).
5279 
5280  If set to zero, no deflation takes place and the def\_var\_deflate
5281  call is ignored. This is slightly different from HDF5 handing of 0
5282  deflate, which turns on the filter but makes only trivial changes to
5283  the data.
5284 
5285  Informal testing at NetCDF World Headquartersggests that there is
5286  little to be gained (with the limited set of test data used here),
5287  in setting the deflate level above 2 or 3.
5288 
5289 Errors
5290 ------
5291 
5292 NF\_DEF\_VAR\_DEFLATE returns the value NF\_NOERR if no errors occurred.
5293 Otherwise, the returned status indicates an error.
5294 
5295 Possible return codes include:
5296 
5297  `NF_NOERR`
5298 : No error.
5299 
5300  `NF_BADID`
5301 : Bad ncid.
5302 
5303  `NF_ENOTNC4`
5304 : Not a netCDF-4 file.
5305 
5306  `NF_ENOTVAR`
5307 : Can’t find this variable.
5308 
5309  `NF_ELATEDEF`
5310 : This variable has already been thebject of a NF\_ENDDEF call. In
5311  netCDF-4 files NF\_ENDDEF will be called automatically for any data
5312  read or write. Once enddef has been called, it is impossible to set
5313  the deflate for a variable.
5314 
5315  `NF_ENOTINDEFINE`
5316 : Not in define mode. This is returned for netCDF classic or 64-bit
5317  offset files, or for netCDF-4 files, when they were been created
5318  with NF\_STRICT\_NC3 flag. (see
5319  [NF\_CREATE](#NF_005fCREATE)).
5320 
5321  `NF_EPERM`
5322 : Attempt to create object in read-only file.
5323 
5324  `NF_EINVAL`
5325 : Invalid deflate\_level. The deflate level must be between 0 and 9,
5326  inclusive.
5327 
5328 Example
5329 -------
5330 
5331 In this example from nf\_test/ftst\_vars.F, a file is created with two
5332 dimensions and one variable. Chunking, deflate, and the fletcher32
5333 filter are turned on. The deflate level is set to 4 below.
5334 
5335  
5336 
5337 
5338 C Create the netCDF file.
5339  retval = nf_create(FILE_NAME, NF_NETCDF4, ncid)
5340  if (retval .ne. nf_noerr) call handle_err(retval)
5341 
5342 C Define the dimensions.
5343  retval = nf_def_dim(ncid, "x", NX, x_dimid)
5344  if (retval .ne. nf_noerr) call handle_err(retval)
5345  retval = nf_def_dim(ncid, "y", NY, y_dimid)
5346  if (retval .ne. nf_noerr) call handle_err(retval)
5347 
5348 C Define the variable.
5349  dimids(1) = y_dimid
5350  dimids(2) = x_dimid
5351  retval = NF_DEF_VAR(ncid, "data", NF_INT, NDIMS, dimids, varid)
5352  if (retval .ne. nf_noerr) call handle_err(retval)
5353 
5354 C Turn on chunking.
5355  chunks(1) = NY
5356  chunks(2) = NX
5357  retval = NF_DEF_VAR_CHUNKING(ncid, varid, NF_CHUNKED, chunks)
5358  if (retval .ne. nf_noerr) call handle_err(retval)
5359 
5360 C Turn on deflate compression, fletcher32 checm.
5361  retval = NF_DEF_VAR_deflate(ncid, varid, 0, 1, 4)
5362  if (retval .ne. nf_noerr) call handle_err(retval)
5363  retval = NF_DEF_VAR_FLETCHER32(ncid, varid, NF_FLETCHER32)
5364  if (retval .ne. nf_noerr) call handle_err(retval)
5365 
5366 
5367 6.11 Learn About Deflate Parameters for a Variable: `NF_INQ_VAR_DEFLATE`
5368 ------------------------------------------------------------------------
5369 
5370 The function NF\_INQ\_VAR\_DEFLATE returns the deflate settings for a
5371 variable in a netCDF-4 file.
5372 
5373 It is not necessary to know the deflate settings to read the variable.
5374 (Deflate is completely transparent to readers of the data).
5375 
5376 Usage
5377 -----
5378 
5379  
5380 
5381 
5382 NF_INQ_VAR_DEFLATE(INTEGER NCID, INTEGER VARID, INTEGER SHUFFLE,
5383  INTEGER DEFLATE, INTEGER DEFLATE_LEVEL);
5384 
5385 
5386  `NCID`
5387 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5388 
5389  `VARID`
5390 : Variable ID.
5391 
5392  `SHUFFLE`
5393 : NF\_INQ\_VAR\_DEFLATE will set this to a 1 if the shuffle filter is
5394  turned on for this variable, and a 0 otherwise.
5395 
5396  `DEFLATE`
5397 : NF\_INQ\_VAR\_DEFLATE will set this to a 1 if the deflate filter is
5398  turned on for this variable, and a 0 otherwise.
5399 
5400  `DEFLATE_LEVEL`
5401 : NF\_INQ\_VAR\_DEFLATE function will write the deflate\_level here,
5402  if deflate is in use.
5403 
5404 Errors
5405 ------
5406 
5407 NF\_INQ\_VAR\_DEFLATE returns the value NF\_NOERR if no errors occurred.
5408 Otherwise, the returned status indicates an error.
5409 
5410 Possible return codes include:
5411 
5412  `NF_NOERR`
5413 : No error.
5414 
5415  `NF_BADID`
5416 : Bad ncid.
5417 
5418  `NF_ENOTNC4`
5419 : Not a netCDF-4 file.
5420 
5421  `NF_ENOTVAR`
5422 : Can’t find this variable.
5423 
5424 Example
5425 -------
5426 
5427 In this example code from nf\_test/ftst\_vars.F, a file with a variable
5428 using deflate is opened, and the deflate level checked.
5429 
5430  
5431 
5432 
5433 C Is everything set that ispposed to be?
5434  retval = nf_inq_var_deflate(ncid, varid, shuffle, deflate,
5435  + deflate_level)
5436  if (retval .ne. nf_noerr) call handle_err(retval)
5437  if (shuffle .ne. 0 .or. deflate .ne. 1 .or.
5438  + deflate_level .ne. 4) stop 2
5439 
5440 
5441 6.12 Learn About Szip Parameters for a Variable: `NF_INQ_VAR_SZIP`
5442 ------------------------------------------------------------------
5443 
5444 The function NF\_INQ\_VAR\_SZIP returns the szip settings for a variable
5445 in a netCDF-4 file.
5446 
5447 It is not necessary to know the szip settings to read the variable.
5448 (Szip is completely transparent to readers of the data).
5449 
5450 Usage
5451 -----
5452 
5453  
5454 
5455 
5456 NF_INQ_VAR_SZIP(INTEGER NCID, INTEGER VARID, INTEGER OPTION_MASK,
5457  PIXELS_PER_BLOCK);
5458 
5459 
5460  `NCID`
5461 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5462 
5463  `VARID`
5464 : Variable ID.
5465 
5466  `OPTION_MASK`
5467 : This will be set to the option\_mask value.
5468 
5469  `PIXELS_PER_BLOCK`
5470 : The number of bits per pixel will be put here.
5471 
5472 Errors
5473 ------
5474 
5475 NF\_INQ\_VAR\_SZIP returns the value NF\_NOERR if no errors occurred.
5476 Otherwise, the returned status indicates an error.
5477 
5478 Possible return codes include:
5479 
5480  `NF_NOERR`
5481 : No error.
5482 
5483  `NF_BADID`
5484 : Bad ncid.
5485 
5486  `NF_ENOTNC4`
5487 : Not a netCDF-4 file.
5488 
5489  `NF_ENOTVAR`
5490 : Can’t find this variable.
5491 
5492 
5493 6.13 Define Checm Parameters for a Variable: `NF_DEF_VAR_FLETCHER32`
5494 -----------------------------------------------------------------------
5495 
5496 The function NF\_DEF\_VAR\_FLETCHER32 sets the checm property for a
5497 variable in a netCDF-4 file.
5498 
5499 This function may only be called after the variable is defined, but
5500 before NF\_ENDDEF is called.
5501 
5502 Usage
5503 -----
5504 
5505  
5506 
5507 
5508 NF_DEF_VAR_FLETCHER32(INTEGER NCID, INTEGER VARID, INTEGER CHECKSUM);
5509 
5510 
5511  `NCID`
5512 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5513 
5514  `VARID`
5515 : Variable ID.
5516 
5517  `CHECKSUM`
5518 : If this is NF\_FLETCHER32, fletcher32 checms will be turned on
5519  for this variable.
5520 
5521 Errors
5522 ------
5523 
5524 NF\_DEF\_VAR\_FLETCHER32 returns the value NF\_NOERR if no errors
5525 occurred. Otherwise, the returned status indicates an error.
5526 
5527 Possible return codes include:
5528 
5529  `NF_NOERR`
5530 : No error.
5531 
5532  `NF_BADID`
5533 : Bad ncid.
5534 
5535  `NF_ENOTNC4`
5536 : Not a netCDF-4 file.
5537 
5538  `NF_ENOTVAR`
5539 : Can’t find this variable.
5540 
5541  `NF_ELATEDEF`
5542 : This variable has already been thebject of a NF\_ENDDEF call. In
5543  netCDF-4 files NF\_ENDDEF will be called automatically for any data
5544  read or write. Once enddef has been called, it is impossible to set
5545  the checm property for a variable.
5546 
5547  `NF_ENOTINDEFINE`
5548 : Not in define mode. This is returned for netCDF classic or 64-bit
5549  offset files, or for netCDF-4 files, when they were been created
5550  with NF\_STRICT\_NC3 flag. (see
5551  [NF\_CREATE](#NF_005fCREATE)).
5552 
5553  `NF_EPERM`
5554 : Attempt to create object in read-only file.
5555 
5556 Example
5557 -------
5558 
5559 In this example from nf\_test/ftst\_vars.F, the variable in a file has
5560 the Fletcher32 checm filter turned on.
5561 
5562  
5563 
5564 
5565 C Create the netCDF file.
5566  retval = nf_create(FILE_NAME, NF_NETCDF4, ncid)
5567  if (retval .ne. nf_noerr) call handle_err(retval)
5568 
5569 C Define the dimensions.
5570  retval = nf_def_dim(ncid, "x", NX, x_dimid)
5571  if (retval .ne. nf_noerr) call handle_err(retval)
5572  retval = nf_def_dim(ncid, "y", NY, y_dimid)
5573  if (retval .ne. nf_noerr) call handle_err(retval)
5574 
5575 C Define the variable.
5576  dimids(1) = y_dimid
5577  dimids(2) = x_dimid
5578  retval = NF_DEF_VAR(ncid, "data", NF_INT, NDIMS, dimids, varid)
5579  if (retval .ne. nf_noerr) call handle_err(retval)
5580 
5581 C Turn on chunking.
5582  chunks(1) = NY
5583  chunks(2) = NX
5584  retval = NF_DEF_VAR_CHUNKING(ncid, varid, NF_CHUNKED, chunks)
5585  if (retval .ne. nf_noerr) call handle_err(retval)
5586 
5587 C Turn on deflate compression, fletcher32 checms.
5588  retval = NF_DEF_VAR_DEFLATE(ncid, varid, 0, 1, 4)
5589  if (retval .ne. nf_noerr) call handle_err(retval)
5590  retval = NF_DEF_VAR_FLETCHER32(ncid, varid, NF_FLETCHER32)
5591  if (retval .ne. nf_noerr) call handle_err(retval)
5592 
5593 
5594 
5595 6.14 Learn About Checm Parameters for a Variable: `NF_INQ_VAR_FLETCHER32`
5596 ----------------------------------------------------------------------------
5597 
5598 The function NF\_INQ\_VAR\_FLETCHER32 returns the checm settings for
5599 a variable in a netCDF-4 file.
5600 
5601 Usage
5602 -----
5603 
5604  
5605 
5606 
5607 NF_INQ_VAR_FLETCHER32(INTEGER NCID, INTEGER VARID, INTEGER CHECKSUM);
5608 
5609 
5610  `NCID`
5611 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5612 
5613  `VARID`
5614 : Variable ID.
5615 
5616  `CHECKSUM`
5617 : NF\_INQ\_VAR\_FLETCHER32 will set this to NF\_FLETCHER32 if the
5618  fletcher32 filter is turned on for this variable, and NF\_NOCHECKSUM
5619  if it is not.
5620 
5621 Errors
5622 ------
5623 
5624 NF\_INQ\_VAR\_FLETCHER32 returns the value NF\_NOERR if no errors
5625 occurred. Otherwise, the returned status indicates an error.
5626 
5627 Possible return codes include:
5628 
5629  `NF_NOERR`
5630 : No error.
5631 
5632  `NF_BADID`
5633 : Bad ncid.
5634 
5635  `NF_ENOTNC4`
5636 : Not a netCDF-4 file.
5637 
5638  `NF_ENOTVAR`
5639 : Can’t find this variable.
5640 
5641 Example
5642 -------
5643 
5644 In this example from nf\_test/ftst\_vars.F the checm filter is
5645 checked for a file. Since it was turned on for this variable, the
5646 checm variable is set to NF\_FLETCHER32.
5647 
5648  
5649 
5650 
5651  retval = nf_inq_var_fletcher32(ncid, varid, checm)
5652  if (retval .ne. nf_noerr) call handle_err(retval)
5653  if (checm .ne. NF_FLETCHER32) stop 2
5654 
5655 
5656 6.15 Define Endianness of a Variable: `NF_DEF_VAR_ENDIAN`
5657 ---------------------------------------------------------
5658 
5659 The function NF\_DEF\_VAR\_ENDIAN sets the endianness for a variable in
5660 a netCDF-4 file.
5661 
5662 This function must be called after the variable is defined, but before
5663 NF\_ENDDEF is called.
5664 
5665 By default, netCDF-4 variables are in native endianness. That is, they
5666 are big-endian on a big-endian machine, and little-endian on a little
5667 endian machine.
5668 
5669 In some cases a user might wish to change from native endianness to
5670 either big or little-endianness. This function allows them to do that.
5671 
5672 Usage
5673 -----
5674 
5675  
5676 
5677 
5678 NF_DEF_VAR_ENDIAN(INTEGER NCID, INTEGER VARID, INTEGER ENDIAN)
5679 
5680 
5681  `NCID`
5682 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5683 
5684  `VARID`
5685 : Variable ID.
5686 
5687  `ENDIAN`
5688 : Set to NF\_ENDIAN\_NATIVE for native endianness. (This is the
5689  default). Set to NF\_ENDIAN\_LITTLE for little endian, or
5690  NF\_ENDIAN\_BIG for big endian.
5691 
5692 Errors
5693 ------
5694 
5695 NF\_DEF\_VAR\_ENDIAN returns the value NF\_NOERR if no errors occurred.
5696 Otherwise, the returned status indicates an error.
5697 
5698 Possible return codes include:
5699 
5700  `NF_NOERR`
5701 : No error.
5702 
5703  `NF_BADID`
5704 : Bad ncid.
5705 
5706  `NF_ENOTNC4`
5707 : Not a netCDF-4 file.
5708 
5709  `NF_ENOTVAR`
5710 : Can’t find this variable.
5711 
5712  `NF_ELATEDEF`
5713 : This variable has already been thebject of a NF\_ENDDEF call. In
5714  netCDF-4 files NF\_ENDDEF will be called automatically for any data
5715  read or write. Once enddef has been called, it is impossible to set
5716  the endianness of a variable.
5717 
5718  `NF_ENOTINDEFINE`
5719 : Not in define mode. This is returned for netCDF classic or 64-bit
5720  offset files, or for netCDF-4 files, when they were been created
5721  with NF\_STRICT\_NC3 flag, and the file is not in define mode. (see
5722  [NF\_CREATE](#NF_005fCREATE)).
5723 
5724  `NF_EPERM`
5725 : Attempt to create object in read-only file.
5726 
5727 Example
5728 -------
5729 
5730 In this example from nf\_test/ftst\_vars.c, a file is created with one
5731 variable, and its endianness is set to NF\_ENDIAN\_BIG.
5732 
5733  
5734 
5735 
5736 C Create the netCDF file.
5737  retval = nf_create(FILE_NAME, NF_NETCDF4, ncid)
5738  if (retval .ne. nf_noerr) call handle_err(retval)
5739 
5740 C Define the dimensions.
5741  retval = nf_def_dim(ncid, "x", NX, x_dimid)
5742  if (retval .ne. nf_noerr) call handle_err(retval)
5743  retval = nf_def_dim(ncid, "y", NY, y_dimid)
5744  if (retval .ne. nf_noerr) call handle_err(retval)
5745 
5746 C Define the variable.
5747  dimids(1) = y_dimid
5748  dimids(2) = x_dimid
5749  retval = NF_DEF_VAR(ncid, "data", NF_INT, NDIMS, dimids, varid)
5750  if (retval .ne. nf_noerr) call handle_err(retval)
5751 
5752 C Turn on chunking.
5753  chunks(1) = NY
5754  chunks(2) = NX
5755  retval = NF_DEF_VAR_chunking(ncid, varid, 0, chunks)
5756  if (retval .ne. nf_noerr) call handle_err(retval)
5757 
5758 C Set variable to big-endian (default is whatever is native to
5759 C writing machine).
5760  retval = NF_DEF_VAR_endian(ncid, varid, NF_ENDIAN_BIG)
5761  if (retval .ne. nf_noerr) call handle_err(retval)
5762 
5763 
5764 6.16 Learn About Endian Parameters for a Variable: `NF_INQ_VAR_ENDIAN`
5765 ----------------------------------------------------------------------
5766 
5767 The function NF\_INQ\_VAR\_ENDIAN returns the endianness settings for a
5768 variable in a netCDF-4 file.
5769 
5770 Usage
5771 -----
5772 
5773  
5774 
5775 
5776 NF_INQ_VAR_ENDIAN(INTEGER NCID, INTEGER VARID, INTEGER ENDIAN)
5777 
5778 
5779  `NCID`
5780 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5781 
5782  `VARID`
5783 : Variable ID.
5784 
5785  `ENDIAN`
5786 : NF\_INQ\_VAR\_ENDIAN will set this to NF\_ENDIAN\_LITTLE if this
5787  variable is stored in little-endian format, NF\_ENDIAN\_BIG if it is
5788  stored in big-endian format, and NF\_ENDIAN\_NATIVE if the
5789  endianness is not set, and the variable is not created yet.
5790 
5791 Errors
5792 ------
5793 
5794 NF\_INQ\_VAR\_ENDIAN returns the value NF\_NOERR if no errors occurred.
5795 Otherwise, the returned status indicates an error.
5796 
5797 Possible return codes include:
5798 
5799  `NF_NOERR`
5800 : No error.
5801 
5802  `NF_BADID`
5803 : Bad ncid.
5804 
5805  `NF_ENOTNC4`
5806 : Not a netCDF-4 file.
5807 
5808  `NF_ENOTVAR`
5809 : Can’t find this variable.
5810 
5811 Example
5812 -------
5813 
5814 In this example from nf\_test/ftst\_vars.F, the endianness of a variable
5815 is checked to makere it is NF\_ENDIAN\_BIG.
5816 
5817  
5818 
5819 
5820  retval = nf_inq_var_endian(ncid, varid, endianness)
5821  if (retval .ne. nf_noerr) call handle_err(retval)
5822  if (endianness .ne. NF_ENDIAN_BIG) stop 2
5823 
5824 
5825 
5826 6.17 Get a Variable ID from Its Name: NF\_INQ\_VARID
5827 ----------------------------------------------------
5828 
5829 The function NF\_INQ\_VARID returns the ID of a netCDF variable, given
5830 its name.
5831 
5832 Usage
5833 -----
5834 
5835  
5836 
5837 
5838 INTEGER FUNCTION NF_INQ_VARID(INTEGER NCID, CHARACTER*(*) NAME,
5839  INTEGER varid)
5840 
5841 
5842  `NCID`
5843 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5844 
5845  `NAME`
5846 : Variable name for which ID is desired.
5847 
5848  `varid`
5849 : Returned variable ID.
5850 
5851 Errors
5852 ------
5853 
5854 NF\_INQ\_VARID returns the value NF\_NOERR if no errors occurred.
5855 Otherwise, the returned status indicates an error. Possible causes of
5856 errors include:
5857 
5858 - The specified variable name is not a valid name for a variable in
5859  the specified netCDF dataset.
5860 - The specified netCDF ID does not refer to an open netCDF dataset.
5861 
5862 Example
5863 -------
5864 
5865 Here is an example using NF\_INQ\_VARID to find out the ID of a variable
5866 named rh in an existing netCDF dataset named foo.nc:
5867 
5868  
5869 
5870 
5871 INCLUDE 'netcdf.inc'
5872  ...
5873 INTEGER STATUS, NCID, RHID
5874  ...
5875 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
5876 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
5877  ...
5878 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
5879 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
5880 
5881 
5882 
5883 6.18 Get Information about a Variable from Its ID: NF\_INQ\_VAR family
5884 ----------------------------------------------------------------------
5885 
5886 A family of functions that returns information about a netCDF variable,
5887 given its ID. Information about a variable includes its name, type,
5888 number of dimensions, a list of dimension IDs describing the shape of
5889 the variable, and the number of variable attributes that have been
5890 assigned to the variable.
5891 
5892 The function NF\_INQ\_VAR returns all the information about a netCDF
5893 variable, given its ID. The other functions each return just one item of
5894 information about a variable.
5895 
5896 These other functions include NF\_INQ\_VARNAME, NF\_INQ\_VARTYPE,
5897 NF\_INQ\_VARNDIMS, NF\_INQ\_VARDIMID, and NF\_INQ\_VARNATTS.
5898 
5899 Usage
5900 -----
5901 
5902  
5903 
5904 
5905 INTEGER FUNCTION NF_INQ_VAR (INTEGER NCID, INTEGER VARID,
5906  CHARACTER*(*) name, INTEGER xtype,
5907  INTEGER ndims, INTEGER dimids(*),
5908  INTEGER natts)
5909 INTEGER FUNCTION NF_INQ_VARNAME (INTEGER NCID, INTEGER VARID,
5910  CHARACTER*(*) name)
5911 INTEGER FUNCTION NF_INQ_VARTYPE (INTEGER NCID, INTEGER VARID,
5912  INTEGER xtype)
5913 INTEGER FUNCTION NF_INQ_VARNDIMS (INTEGER NCID, INTEGER VARID,
5914  INTEGER ndims)
5915 INTEGER FUNCTION NF_INQ_VARDIMID (INTEGER NCID, INTEGER VARID,
5916  INTEGER dimids(*))
5917 INTEGER FUNCTION NF_INQ_VARNATTS (INTEGER NCID, INTEGER VARID,
5918  INTEGER natts)
5919 
5920 
5921  `NCID`
5922 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
5923 
5924  `VARID`
5925 : Variable ID.
5926 
5927  `NAME`
5928 : Returned variable name. The caller must allocate space for the
5929  returned name. The maximum possible length, in characters, of a
5930  variable name is given by the predefined constant NF\_MAX\_NAME.
5931 
5932  `xtype`
5933 : Returned variable type, one of the set of predefined netCDF external
5934  data types. The type of this parameter, NF\_TYPE, is defined in the
5935  netCDF header file. The valid netCDF external data types are
5936  NF\_BYTE, NF\_CHAR, NF\_SHORT, NF\_INT, NF\_FLOAT, AND NF\_DOUBLE.
5937 
5938  `ndims`
5939 : Returned number of dimensions the variable was defined as using. For
5940  example, 2 indicates a matrix, 1 indicates a vector, and 0 means the
5941  variable is a scalar with no dimensions.
5942 
5943  `dimids`
5944 : Returned vector of \*ndimsp dimension IDs corresponding to the
5945  variable dimensions. The caller must allocate enough space for a
5946  vector of at least \*ndimsp integers to be returned. The maximum
5947  possible number of dimensions for a variable is given by the
5948  predefined constant NF\_MAX\_VAR\_DIMS.
5949 
5950  `natts`
5951 : Returned number of variable attributes assigned to this variable.
5952 
5953 These functions return the value NF\_NOERR if no errors occurred.
5954 Otherwise, the returned status indicates an error. Possible causes of
5955 errors include:
5956 
5957 - The variable ID is invalid for the specified netCDF dataset.
5958 - The specified netCDF ID does not refer to an open netCDF dataset.
5959 
5960 Example
5961 -------
5962 
5963 Here is an example using NF\_INQ\_VAR to find out about a variable named
5964 rh in an existing netCDF dataset named foo.nc:
5965 
5966  
5967 
5968 
5969 INCLUDE 'netcdf.inc'
5970  ...
5971 INTEGER STATUS, NCID
5972 INTEGER RHID ! variable ID
5973 CHARACTER*31 RHNAME ! variable name
5974 INTEGER RHTYPE ! variable type
5975 INTEGER RHN ! number of dimensions
5976 INTEGER RHDIMS(NF_MAX_VAR_DIMS) ! variable shape
5977 INTEGER RHNATT ! number of attributes
5978  ...
5979 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
5980 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
5981  ...
5982 STATUS = NF_INQ_VARID (NCID, 'rh', RHID) ! get ID
5983 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
5984 STATUS = NF_INQ_VAR (NCID, RHID, RHNAME, RHTYPE, RHN, RHDIMS, RHNATT)
5985 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
5986 
5987 
5988 6.19 Write a Single Data Value: NF\_PUT\_VAR1\_ type
5989 ----------------------------------------------------
5990 
5991 The functions NF\_PUT\_VAR1\_type (for various types) put a single data
5992 value of the specified type into a variable of an open netCDF dataset
5993 that is in data mode. Inputs are the netCDF ID, the variable ID, an
5994 index that specifies which value to add or alter, and the data value.
5995 The value is converted to the external data type of the variable, if
5996 necessary.
5997 
5998 Usage
5999 -----
6000 
6001  
6002 
6003 
6004 INTEGER FUNCTION NF_PUT_VAR1_TEXT(INTEGER NCID, INTEGER VARID,
6005  INTEGER INDEX(*), CHARACTER CHVAL)
6006 INTEGER FUNCTION NF_PUT_VAR1_INT1(INTEGER NCID, INTEGER VARID,
6007  INTEGER INDEX(*), INTEGER*1 I1VAL)
6008 INTEGER FUNCTION NF_PUT_VAR1_INT2(INTEGER NCID, INTEGER VARID,
6009  INTEGER INDEX(*), INTEGER*2 I2VAL)
6010 INTEGER FUNCTION NF_PUT_VAR1_INT (INTEGER NCID, INTEGER VARID,
6011  INTEGER INDEX(*), INTEGER IVAL)
6012 INTEGER FUNCTION NF_PUT_VAR1_REAL(INTEGER NCID, INTEGER VARID,
6013  INTEGER INDEX(*), REAL RVAL)
6014 INTEGER FUNCTION NF_PUT_VAR1_DOUBLE(INTEGER NCID, INTEGER VARID,
6015  INTEGER INDEX(*), DOUBLE DVAL)
6016 INTEGER FUNCTION NF_PUT_VAR1(INTEGER NCID, INTEGER VARID,
6017  INTEGER INDEX(*), *)
6018 
6019 
6020  `NCID`
6021 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6022 
6023  `VARID`
6024 : Variable ID.
6025 
6026  `INDEX`
6027 : The index of the data value to be written. The indices are relative
6028  to 1, so for example, the first data value of a two-dimensional
6029  variable would have index (1,1). The elements of index must
6030  correspond to the variable’s dimensions. Hence, if the variable uses
6031  the unlimited dimension, the last index would correspond to the
6032  record number.
6033 
6034  `CHVAL`\
6035  `I1VAL`\
6036  `I2VAL`\
6037  `IVAL`\
6038  `RVAL`\
6039  `DVAL`
6040 : Pointer to the data value to be written. If the type of data values
6041  differs from the netCDF variable type, type conversion will occur.
6042  See [(netcdf)Type Conversion](netcdf.html#Type-Conversion)
6043  ‘Type Conversion’ in The NetCDF Users Guide.
6044 
6045 Errors
6046 ------
6047 
6048 NF\_PUT\_VAR1\_ type returns the value NF\_NOERR if no errors occurred.
6049 Otherwise, the returned status indicates an error. Possible causes of
6050 errors include:
6051 
6052 - The variable ID is invalid for the specified netCDF dataset.
6053 - The specified indices were out of range for the rank of the
6054  specified variable. For example, a negative index or an index that
6055  is larger than the corresponding dimension length will cause an
6056  error.
6057 - The specified value is out of the range of values representable by
6058  the external data type of the variable.
6059 - The specified netCDF is in define mode rather than data mode.
6060 - The specified netCDF ID does not refer to an open netCDF dataset.
6061 
6062 Example
6063 -------
6064 
6065 Here is an example using NF\_PUT\_VAR1\_DOUBLE to set the (4,3,2)
6066 element of the variable named rh to 0.5 in an existing netCDF dataset
6067 named foo.nc. For simplicity in this example, we ame that we know
6068 that rh is dimensioned with lon, lat, and time, so we want to set the
6069 value of rh that corresponds to the fourth lon value, the third lat
6070 value, and the second time value:
6071 
6072  
6073 
6074 
6075 INCLUDE 'netcdf.inc'
6076  ...
6077 INTEGER STATUS ! error status
6078 INTEGER NCID
6079 INTEGER RHID ! variable ID
6080 INTEGER RHINDX(3) ! where to put value
6081 DATA RHINDX /4, 3, 2/
6082  ...
6083 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
6084 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6085  ...
6086 STATUS = NF_INQ_VARID (NCID, 'rh', RHID) ! get ID
6087 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6088 STATUS = NF_PUT_VAR1_DOUBLE (NCID, RHID, RHINDX, 0.5)
6089 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6090 
6091 
6092 6.20 Write an Entire Variable: NF\_PUT\_VAR\_ type
6093 --------------------------------------------------
6094 
6095 The NF\_PUT\_VAR\_ type family of functions write all the values of a
6096 variable into a netCDF variable of an open netCDF dataset. This is the
6097 simplest interface to use for writing a value in a scalar variable or
6098 whenever all the values of a multidimensional variable can all be
6099 written at once. The values to be written are associated with the netCDF
6100 variable by aming that the last dimension of the netCDF variable
6101 varies fastest in the C interface. The values are converted to the
6102 external data type of the variable, if necessary.
6103 
6104 Take care when using the simplest forms of this interface with record
6105 variables (variables that use the NF\_UNLIMITED dimension) when you
6106 don’t specify how many records are to be written. If you try to write
6107 all the values of a record variable into a netCDF file that has no
6108 record data yet (hence has 0 records), nothing will be written.
6109 Similarly, if you try to write all the values of a record variable from
6110 an array but there are more records in the file than you ame, more
6111 in-memory data will be accessed than you expect, which may cause a
6112 segmentation violation. To avoidch problems, it is better to use the
6113 NF\_PUT\_VARA\_type interfaces for variables that use the NF\_UNLIMITED
6114 dimension. See [Write an Array of Values: NF\_PUT\_VARA\_
6115 type](#NF_005fPUT_005fVARA_005f-type).
6116 
6117 Usage
6118 -----
6119 
6120  
6121 
6122 
6123 INTEGER FUNCTION NF_PUT_VAR_TEXT (INTEGER NCID, INTEGER VARID,
6124  CHARACTER*(*) TEXT)
6125 INTEGER FUNCTION NF_PUT_VAR_INT1 (INTEGER NCID, INTEGER VARID,
6126  INTEGER*1 I1VALS(*))
6127 INTEGER FUNCTION NF_PUT_VAR_INT2 (INTEGER NCID, INTEGER VARID,
6128  INTEGER*2 I2VALS(*))
6129 INTEGER FUNCTION NF_PUT_VAR_INT (INTEGER NCID, INTEGER VARID,
6130  INTEGER IVALS(*))
6131 INTEGER FUNCTION NF_PUT_VAR_REAL (INTEGER NCID, INTEGER VARID,
6132  REAL RVALS(*))
6133 INTEGER FUNCTION NF_PUT_VAR_DOUBLE(INTEGER NCID, INTEGER VARID,
6134  DOUBLE DVALS(*))
6135 INTEGER FUNCTION NF_PUT_VAR (INTEGER NCID, INTEGER VARID,
6136  VALS(*))
6137 
6138 
6139  `NCID`
6140 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6141 
6142  `VARID`
6143 : Variable ID.
6144 
6145  `TEXT`\
6146  `I1VALS`\
6147  `I2VALS`\
6148  `IVALS`\
6149  `RVALS`\
6150  `DVALS`\
6151  `VALS`
6152 : The block of data values to be written. The data should be of the
6153  type appropriate for the function called. You cannot put CHARACTER
6154  data into a numeric variable or numeric data into a text variable.
6155  For numeric data, if the type of data differs from the netCDF
6156  variable type, type conversion will occur (see [(netcdf)Type
6157  Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6158  in The NetCDF Users Guide). The order in which the data will be
6159  written into the specified variable is with the first dimension
6160  varying fastest (like the ordinary FORTRAN convention).
6161 
6162 Errors
6163 ------
6164 
6165 Members of the NF\_PUT\_VAR\_ type family return the value NF\_NOERR if
6166 no errors occurred. Otherwise, the returned status indicates an error.
6167 Possible causes of errors include:
6168 
6169 - The variable ID is invalid for the specified netCDF dataset.
6170 - One or more of the specified values are out of the range of values
6171  representable by the external data type of the variable.
6172 - One or more of the specified values are out of the range of values
6173  representable by the external data type of the variable.
6174 - The specified netCDF dataset is in define mode rather than data
6175  mode.
6176 - The specified netCDF ID does not refer to an open netCDF dataset.
6177 
6178 Example
6179 -------
6180 
6181 Here is an example using NF\_PUT\_VAR\_DOUBLE to add or change all the
6182 values of the variable named rh to 0.5 in an existing netCDF dataset
6183 named foo.nc. For simplicity in this example, we ame that we know
6184 that rh is dimensioned with lon and lat, and that there are ten lon
6185 values and five lat values.
6186 
6187  
6188 
6189 
6190 INCLUDE 'netcdf.inc'
6191  ...
6192 PARAMETER (LATS=5, LONS=10) ! dimension lengths
6193 INTEGER STATUS, NCID
6194 INTEGER RHID ! variable ID
6195 DOUBLE RHVALS(LONS, LATS)
6196  ...
6197 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
6198 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6199  ...
6200 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
6201 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6202 DO 10 ILON = 1, LONS
6203  DO 10 ILAT = 1, LATS
6204  RHVALS(ILON, ILAT) = 0.5
6205 10 CONTINUE
6206 STATUS = NF_PUT_var_DOUBLE (NCID, RHID, RHVALS)
6207 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6208 
6209 
6210 
6211 6.21 Write an Array of Values: NF\_PUT\_VARA\_ type
6212 ---------------------------------------------------
6213 
6214 The function NF\_PUT\_VARA\_ type writes values into a netCDF variable
6215 of an open netCDF dataset. The part of the netCDF variable to write is
6216 specified by giving a corner and a vector of edge lengths that refer to
6217 an array of the netCDF variable. The values to be written are
6218 associated with the netCDF variable by aming that the first dimension
6219 of the netCDF variable varies fastest in the FORTRAN interface. The
6220 netCDF dataset must be in data mode.
6221 
6222 Usage
6223 -----
6224 
6225  
6226 
6227 
6228 INTEGER FUNCTION NF_PUT_VARA_TEXT(INTEGER NCID, INTEGER VARID,
6229  INTEGER START(*), INTEGER COUNT(*),
6230  CHARACTER*(*) TEXT)
6231 INTEGER FUNCTION NF_PUT_VARA_INT1(INTEGER NCID, INTEGER VARID,
6232  INTEGER START(*), INTEGER COUNT(*),
6233  INTEGER*1 I1VALS(*))
6234 INTEGER FUNCTION NF_PUT_VARA_INT2(INTEGER NCID, INTEGER VARID,
6235  INTEGER START(*), INTEGER COUNT(*),
6236  INTEGER*2 I2VALS(*))
6237 INTEGER FUNCTION NF_PUT_VARA_INT (INTEGER NCID, INTEGER VARID,
6238  INTEGER START(*), INTEGER COUNT(*),
6239  INTEGER IVALS(*))
6240 INTEGER FUNCTION NF_PUT_VARA_REAL(INTEGER NCID, INTEGER VARID,
6241  INTEGER START(*), INTEGER COUNT(*),
6242  REAL RVALS(*))
6243 INTEGER FUNCTION NF_PUT_VARA_DOUBLE(INTEGER NCID, INTEGER VARID,
6244  INTEGER START(*), INTEGER COUNT(*),
6245  DOUBLE DVALS(*))
6246 INTEGER FUNCTION NF_PUT_VARA (INTEGER NCID, INTEGER VARID,
6247  INTEGER START(*), INTEGER COUNT(*),
6248  VALS(*))
6249 
6250 
6251  `NCID`
6252 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6253 
6254  `VARID`
6255 : Variable ID.
6256 
6257  `START`
6258 : A vector of integers specifying the index in the variable where the
6259  first of the data values will be written. The indices are relative
6260  to 1, so for example, the first data value of a variable would have
6261  index (1, 1, ..., 1). The length of START must be the same as the
6262  number of dimensions of the specified variable. The elements of
6263  START must correspond to the variable’s dimensions in order. Hence,
6264  if the variable is a record variable, the last index would
6265  correspond to the starting record number for writing the data
6266  values.
6267 
6268  `COUNT`
6269 : A vector of integers specifying the edge lengths along each
6270  dimension of the block of data values to written. To write a single
6271  value, for example, specify COUNT as (1, 1, ..., 1). The length of
6272  COUNT is the number of dimensions of the specified variable. The
6273  elements of COUNT correspond to the variable’s dimensions. Hence, if
6274  the variable is a record variable, the last element of COUNT
6275  corresponds to a count of the number of records to write.
6276 
6277  Note: setting any element of the count array to zero causes the
6278  function to exit without error, and without doing anything.
6279 
6280  `TEXT`\
6281  `I1VALS`\
6282  `I2VALS`\
6283  `IVALS`\
6284  `RVALS`\
6285  `DVALS`\
6286  `VALS`
6287 : The block of data values to be written. The data should be of the
6288  type appropriate for the function called. You cannot put CHARACTER
6289  data into a numeric variable or numeric data into a text variable.
6290  For numeric data, if the type of data differs from the netCDF
6291  variable type, type conversion will occur (see [(netcdf)Type
6292  Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6293  in The NetCDF Users Guide).
6294 
6295 Errors
6296 ------
6297 
6298 NF\_PUT\_VARA\_ type returns the value NF\_NOERR if no errors occurred.
6299 Otherwise, the returned status indicates an error. Possible causes of
6300 errors include:
6301 
6302 - The variable ID is invalid for the specified netCDF dataset.
6303 - The specified corner indices were out of range for the rank of the
6304  specified variable. For example, a negative index, or an index that
6305  is larger than the corresponding dimension length will cause an
6306  error.
6307 - The specified edge lengths added to the specified corner would have
6308  referenced data out of range for the rank of the specified variable.
6309  For example, an edge length that is larger than the corresponding
6310  dimension length minus the corner index will cause an error.
6311 - One or more of the specified values are out of the range of values
6312  representable by the external data type of the variable.
6313 - The specified netCDF dataset is in define mode rather than data
6314  mode.
6315 - The specified netCDF ID does not refer to an open netCDF dataset.
6316 
6317 Example
6318 -------
6319 
6320 Here is an example using NF\_PUT\_VARA\_DOUBLE to add or change all the
6321 values of the variable named rh to 0.5 in an existing netCDF dataset
6322 named foo.nc. For simplicity in this example, we ame that we know
6323 that rh is dimensioned with time, lat, and lon, and that there are three
6324 time values, five lat values, and ten lon values.
6325 
6326  
6327 
6328 
6329 INCLUDE 'netcdf.inc'
6330  ...
6331 PARAMETER (NDIMS=3) ! number of dimensions
6332 PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
6333 INTEGER STATUS, NCID, TIMES
6334 INTEGER RHID ! variable ID
6335 INTEGER START(NDIMS), COUNT(NDIMS)
6336 DOUBLE RHVALS(LONS, LATS, TIMES)
6337 DATA START /1, 1, 1/ ! start at first value
6338 DATA COUNT /LONS, LATS, TIMES/
6339  ...
6340 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
6341 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6342  ...
6343 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
6344 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6345 DO 10 ILON = 1, LONS
6346  DO 10 ILAT = 1, LATS
6347  DO 10 ITIME = 1, TIMES
6348  RHVALS(ILON, ILAT, ITIME) = 0.5
6349 10 CONTINUE
6350 STATUS = NF_PUT_VARA_DOUBLE (NCID, RHID, START, COUNT, RHVALS)
6351 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6352 
6353 
6354 
6355 6.22 NF\_PUT\_VARS\_ type
6356 -------------------------
6357 
6358 Each member of the family of functions NF\_PUT\_VARS\_ type writes a
6359 subsampled (strided) array of values into a netCDF variable of
6360 an open netCDF dataset. Thebsampled array is specified by
6361 giving a corner, a vector of counts, and a stride vector. The netCDF
6362 dataset must be in data mode.
6363 
6364 Usage
6365 -----
6366 
6367  
6368 
6369 
6370 INTEGER FUNCTION NF_PUT_VARS_TEXT (INTEGER NCID, INTEGER VARID,
6371  INTEGER START(*), INTEGER COUNT(*),
6372  INTEGER STRIDE(*),CHARACTER*(*) TEXT)
6373 INTEGER FUNCTION NF_PUT_VARS_INT1 (INTEGER NCID, INTEGER VARID,
6374  INTEGER START(*), INTEGER COUNT(*),
6375  INTEGER STRIDE(*),INTEGER*1 I1VALS(*))
6376 INTEGER FUNCTION NF_PUT_VARS_INT2 (INTEGER NCID, INTEGER VARID,
6377  INTEGER START(*), INTEGER COUNT(*),
6378  INTEGER STRIDE(*),INTEGER*2 I2VALS(*))
6379 INTEGER FUNCTION NF_PUT_VARS_INT (INTEGER NCID, INTEGER VARID,
6380  INTEGER START(*), INTEGER COUNT(*),
6381  INTEGER STRIDE(*), INTEGER IVALS(*))
6382 INTEGER FUNCTION NF_PUT_VARS_REAL (INTEGER NCID, INTEGER VARID,
6383  INTEGER START(*), INTEGER COUNT(*),
6384  INTEGER STRIDE(*), REAL RVALS(*))
6385 INTEGER FUNCTION NF_PUT_VARS_DOUBLE(INTEGER NCID, INTEGER VARID,
6386  INTEGER START(*), INTEGER COUNT(*),
6387  INTEGER STRIDE(*), DOUBLE DVALS(*))
6388 INTEGER FUNCTION NF_PUT_VARS (INTEGER NCID, INTEGER VARID,
6389  INTEGER START(*), INTEGER COUNT(*),
6390  INTEGER STRIDE(*), VALS(*))
6391 
6392 
6393  `NCID`
6394 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6395 
6396  `VARID`
6397 : Variable ID.
6398 
6399  `START`
6400 : A vector of integers specifying the index in the variable where the
6401  first of the data values will be written. The indices are relative
6402  to 1, so for example, the first data value of a variable would have
6403  index (1, 1, ..., 1). The elements of START correspond, in order, to
6404  the variable’s dimensions. Hence, if the variable is a record
6405  variable, the last index would correspond to the starting record
6406  number for writing the data values.
6407 
6408  `COUNT`
6409 : A vector of integers specifying the number of indices selected along
6410  each dimension. To write a single value, for example, specify COUNT
6411  as (1, 1, ..., 1). The elements of COUNT correspond, in order, to
6412  the variable’s dimensions. Hence, if the variable is a record
6413  variable, the last element of COUNT corresponds to a count of the
6414  number of records to write.
6415 
6416  Note: setting any element of the count array to zero causes the
6417  function to exit without error, and without doing anything.
6418 
6419  `STRIDE`
6420 : A vector of integers that specifies the sampling interval along each
6421  dimension of the netCDF variable. The elements of the stride vector
6422  correspond, in order, to the netCDF variable’s dimensions (STRIDE(1)
6423  gives the sampling interval along the most rapidly varying dimension
6424  of the netCDF variable). Sampling intervals are specified in
6425  type-independent units of elements (a value of 1 selects consecutive
6426  elements of the netCDF variable along the corresponding dimension, a
6427  value of 2 selects every other element, etc.).
6428 
6429  `TEXT`\
6430  `I1VALS`\
6431  `I2VALS`\
6432  `IVALS`\
6433  `RVALS`\
6434  `DVALS`\
6435  `VALS`
6436 : The block of data values to be written. The data should be of the
6437  type appropriate for the function called. You cannot put CHARACTER
6438  data into a numeric variable or numeric data into a text variable.
6439  For numeric data, if the type of data differs from the netCDF
6440  variable type, type conversion will occur (see [(netcdf)Type
6441  Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6442  in The NetCDF Users Guide).
6443 
6444 Errors
6445 ------
6446 
6447 NF\_PUT\_VARS\_ type returns the value NF\_NOERR if no errors occurred.
6448 Otherwise, the returned status indicates an error. Possible causes of
6449 errors include:
6450 
6451 - The variable ID is invalid for the specified netCDF dataset.
6452 - The specified start, count and stride generate an index which is out
6453  of range.
6454 - One or more of the specified values are out of the range of values
6455  representable by the external data type of the variable.
6456 - The specified netCDF is in define mode rather than data mode.
6457 - The specified netCDF ID does not refer to an open netCDF dataset.
6458 
6459 Example
6460 -------
6461 
6462 Here is an example of using NF\_PUT\_VARS\_REAL to write – from an
6463 internal array – every other point of a netCDF variable named rh which
6464 is described by the FORTRAN declaration REAL RH(6,4) (note the size of
6465 the dimensions):
6466 
6467  
6468 
6469 
6470 INCLUDE 'netcdf.inc'
6471  ...
6472 PARAMETER (NDIM=2) ! rank of netCDF variable
6473 INTEGER NCID ! netCDF dataset ID
6474 INTEGER STATUS ! return code
6475 INTEGER RHID ! variable ID
6476 INTEGER START(NDIM) ! netCDF variable start point
6477 INTEGER COUNT(NDIM) ! size of internal array
6478 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
6479 REAL RH(3,2) ! notebsampled sizes for netCDF variable
6480  ! dimensions
6481 DATA START /1, 1/ ! start at first netCDF variable value
6482 DATA COUNT /3, 2/ ! size of internal array: entire bsampled)
6483  ! netCDF variable
6484 DATA STRIDE /2, 2/ ! access every other netCDF element
6485  ...
6486 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
6487 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6488  ...
6489 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
6490 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6491  ...
6492 STATUS = NF_PUT_VARS_REAL(NCID, RHID, START, COUNT, STRIDE, RH)
6493 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6494 
6495 6.23 NF\_PUT\_VARM\_ type
6496 -------------------------
6497 
6498 The NF\_PUT\_VARM\_ type family of functions writes a mapped array
6499 section of values into a netCDF variable of an open netCDF dataset. The
6500 mapped array is specified by giving a corner, a vector of
6501 counts, a stride vector, and an index mapping vector. The index mapping
6502 vector is a vector of integers that specifies the mapping between the
6503 dimensions of a netCDF variable and the in-memory structure of the
6504 internal data array. No amptions are made about the ordering or
6505 length of the dimensions of the data array. The netCDF dataset must be
6506 in data mode.
6507 
6508 Usage
6509 -----
6510 
6511  
6512 
6513 
6514 INTEGER FUNCTION NF_PUT_VARM_TEXT (INTEGER NCID, INTEGER VARID,
6515  INTEGER START(*), INTEGER COUNT(*),
6516  INTEGER STRIDE(*), INTEGER IMAP(*),
6517  CHARACTER*(*) TEXT)
6518 INTEGER FUNCTION NF_PUT_VARM_INT1 (INTEGER NCID, INTEGER VARID,
6519  INTEGER START(*), INTEGER COUNT(*),
6520  INTEGER STRIDE(*), INTEGER IMAP(*),
6521  INTEGER*1 I1VALS(*))
6522 INTEGER FUNCTION NF_PUT_VARM_INT2 (INTEGER NCID, INTEGER VARID,
6523  INTEGER START(*), INTEGER COUNT(*),
6524  INTEGER STRIDE(*), INTEGER IMAP(*),
6525  INTEGER*2 I2VALS(*))
6526 INTEGER FUNCTION NF_PUT_VARM_INT (INTEGER NCID, INTEGER VARID,
6527  INTEGER START(*), INTEGER COUNT(*),
6528  INTEGER STRIDE(*), INTEGER IMAP(*),
6529  INTEGER IVALS(*))
6530 INTEGER FUNCTION NF_PUT_VARM_REAL (INTEGER NCID, INTEGER VARID,
6531  INTEGER START(*), INTEGER COUNT(*),
6532  INTEGER STRIDE(*), INTEGER IMAP(*),
6533  REAL RVALS(*))
6534 INTEGER FUNCTION NF_PUT_VARM_DOUBLE(INTEGER NCID, INTEGER VARID,
6535  INTEGER START(*), INTEGER COUNT(*),
6536  INTEGER STRIDE(*), INTEGER IMAP(*),
6537  DOUBLE DVALS(*))
6538 
6539 
6540  `NCID`
6541 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6542 
6543  `VARID`
6544 : Variable ID.
6545 
6546  `START`
6547 : A vector of integers specifying the index in the variable where the
6548  first of the data values will be written. The indices are relative
6549  to 1, so for example, the first data value of a variable would have
6550  index (1, 1, ..., 1). The elements of START correspond, in order, to
6551  the variable’s dimensions. Hence, if the variable is a record
6552  variable, the last index would correspond to the starting record
6553  number for writing the data values.
6554 
6555  `COUNT`
6556 : A vector of integers specifying the number of indices selected along
6557  each dimension. To write a single value, for example, specify COUNT
6558  as (1, 1, ..., 1). The elements of COUNT correspond, in order, to
6559  the variable’s dimensions. Hence, if the variable is a record
6560  variable, the last element of COUNT corresponds to a count of the
6561  number of records to write.
6562 
6563  Note: setting any element of the count array to zero causes the
6564  function to exit without error, and without doing anything.
6565 
6566  `STRIDE`
6567 : A vector of integers that specifies the sampling interval along each
6568  dimension of the netCDF variable. The elements of the stride vector
6569  correspond, in order, to the netCDF variable’s dimensions (STRIDE(1)
6570  gives the sampling interval along the most rapidly varying dimension
6571  of the netCDF variable). Sampling intervals are specified in
6572  type-independent units of elements (a value of 1 selects consecutive
6573  elements of the netCDF variable along the corresponding dimension, a
6574  value of 2 selects every other element, etc.).
6575 
6576  `IMAP`
6577 : A vector of integers that specifies the mapping between the
6578  dimensions of a netCDF variable and the in-memory structure of the
6579  internal data array. The elements of the index mapping vector
6580  correspond, in order, to the netCDF variable’s dimensions (IMAP(1)
6581  gives the distance between elements of the internal array
6582  corresponding to the most rapidly varying dimension of the netCDF
6583  variable). Distances between elements are specified in units of
6584  elements (the distance between internal elements that occupy
6585  adjacent memory locations is 1 and not the element’s byte-length as
6586  in netCDF 2).
6587 
6588  `TEXT`\
6589  `I1VALS`\
6590  `I2VALS`\
6591  `IVALS`\
6592  `RVALS`\
6593  `DVALS`
6594 : The data values to be written. The data should be of the type
6595  appropriate for the function called. You cannot put CHARACTER data
6596  into a numeric variable or numeric data into a text variable. For
6597  numeric data, if the type of data differs from the netCDF variable
6598  type, type conversion will occur (see [(netcdf)Type
6599  Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6600  in The NetCDF Users Guide).
6601 
6602 Errors
6603 ------
6604 
6605 NF\_PUT\_VARM\_ type returns the value NF\_NOERR if no errors occurred.
6606 Otherwise, the returned status indicates an error. Possible causes of
6607 errors include:
6608 
6609 - The variable ID is invalid for the specified netCDF dataset.
6610 - The specified START, COUNT, and STRIDE generate an index which is
6611  out of range. Note that no error checking is possible on the imap
6612  vector.
6613 - One or more of the specified values are out of the range of values
6614  representable by the external data type of the variable.
6615 - The specified netCDF is in define mode rather than data mode.
6616 - The specified netCDF ID does not refer to an open netCDF dataset.
6617 
6618 Example
6619 -------
6620 
6621 The following IMAP vector maps in the trivial way a 2x3x4 netCDF
6622 variable and an internal array of the same shape:
6623 
6624  
6625 
6626 
6627 REAL A(2,3,4) ! same shape as netCDF variable
6628 INTEGER IMAP(3)
6629 DATA IMAP /1, 2, 6/ ! netCDF dimension inter-element distance
6630  ! ---------------- ----------------------
6631  ! most rapidly varying 1
6632  ! intermediate 2 (=IMAP(1)*2)
6633  ! most slowly varying 6 (=IMAP(2)*3)
6634 
6635 
6636 Using the IMAP vector above with NF\_PUT\_VARM\_REAL obtains the same
6637 rlt as simply using NF\_PUT\_VAR\_REAL.
6638 
6639 Here is an example of using NF\_PUT\_VARM\_REAL to write – from a
6640 transposed, internal array – a netCDF variable named rh which is
6641 described by the FORTRAN declaration REAL RH(4,6) (note the size and
6642 order of the dimensions):
6643 
6644  
6645 
6646 
6647 INCLUDE 'netcdf.inc'
6648  ...
6649 PARAMETER (NDIM=2) ! rank of netCDF variable
6650 INTEGER NCID ! netCDF ID
6651 INTEGER STATUS ! return code
6652 INTEGER RHID ! variable ID
6653 INTEGER START(NDIM) ! netCDF variable start point
6654 INTEGER COUNT(NDIM) ! size of internal array
6655 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
6656 INTEGER IMAP(NDIM) ! internal array inter-element distances
6657 REAL RH(6,4) ! note transposition of netCDF variable dimensions
6658 DATA START /1, 1/ ! start at first netCDF variable element
6659 DATA COUNT /4, 6/ ! entire netCDF variable; order corresponds
6660  ! to netCDF variable -- not internal array
6661 DATA STRIDE /1, 1/ ! sample every netCDF element
6662 DATA IMAP /6, 1/ ! would be /1, 4/ if not transposing
6663 
6664 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
6665 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6666  ...
6667 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
6668 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6669  ...
6670 STATUS = NF_PUT_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
6671 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6672 
6673 
6674 Here is another example of using NF\_PUT\_VARM\_REAL to write – from a
6675 transposed, internal array – absample of the same netCDF variable, by
6676 writing every other point of the netCDF variable:
6677 
6678  
6679 
6680 
6681 INCLUDE 'netcdf.inc'
6682  ...
6683 PARAMETER (NDIM=2) ! rank of netCDF variable
6684 INTEGER NCID ! netCDF dataset ID
6685 INTEGER STATUS ! return code
6686 INTEGER RHID ! variable ID
6687 INTEGER START(NDIM) ! netCDF variable start point
6688 INTEGER COUNT(NDIM) ! size of internal array
6689 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
6690 INTEGER IMAP(NDIM) ! internal array inter-element distances
6691 REAL RH(3,2) ! note transposition of bsampled) dimensions
6692 DATA START /1, 1/ ! start at first netCDF variable value
6693 DATA COUNT /2, 3/ ! order of bsampled) dimensions corresponds
6694  ! to netCDF variable -- not internal array
6695 DATA STRIDE /2, 2/ ! sample every other netCDF element
6696 DATA IMAP /3, 1/ ! would be `1, 2' if not transposing
6697  ...
6698 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
6699 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6700  ...
6701 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
6702 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6703  ...
6704 STATUS = NF_PUT_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
6705 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6706 
6707 
6708 6.24 NF\_GET\_VAR1\_ type
6709 -------------------------
6710 
6711 The functions NF\_GET\_VAR1\_ type get a single data value from a
6712 variable of an open netCDF dataset that is in data mode. Inputs are the
6713 netCDF ID, the variable ID, a multidimensional index that specifies
6714 which value to get, and the address of a location into which the data
6715 value will be read. The value is converted from the external data type
6716 of the variable, if necessary.
6717 
6718 Usage
6719 -----
6720 
6721  
6722 
6723 
6724 INTEGER FUNCTION NF_GET_VAR1_TEXT(INTEGER NCID, INTEGER VARID,
6725  INTEGER INDEX(*), CHARACTER CHVAL)
6726 INTEGER FUNCTION NF_GET_VAR1_INT1(INTEGER NCID, INTEGER VARID,
6727  INTEGER INDEX(*), INTEGER*1 I1VAL)
6728 INTEGER FUNCTION NF_GET_VAR1_INT2(INTEGER NCID, INTEGER VARID,
6729  INTEGER INDEX(*), INTEGER*2 I2VAL)
6730 INTEGER FUNCTION NF_GET_VAR1_INT (INTEGER NCID, INTEGER VARID,
6731  INTEGER INDEX(*), INTEGER IVAL)
6732 INTEGER FUNCTION NF_GET_VAR1_REAL(INTEGER NCID, INTEGER VARID,
6733  INTEGER INDEX(*), REAL RVAL)
6734 INTEGER FUNCTION NF_GET_VAR1_DOUBLE(INTEGER NCID, INTEGER VARID,
6735  INTEGER INDEX(*), DOUBLE DVAL)
6736 INTEGER FUNCTION NF_GET_VAR1(INTEGER NCID, INTEGER VARID,
6737  INTEGER INDEX(*), VAL)
6738 
6739 
6740  `NCID`
6741 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6742 
6743  `VARID`
6744 : Variable ID.
6745 
6746  `INDEX`
6747 : The index of the data value to be read. The indices are relative to
6748  1, so for example, the first data value of a two-dimensional
6749  variable has index (1,1). The elements of index correspond to the
6750  variable’s dimensions. Hence, if the variable is a record variable,
6751  the last index is the record number.
6752 
6753  `CHVAL`\
6754  `I1VAL`\
6755  `I2VAL`\
6756  `IVAL`\
6757  `RVAL`\
6758  `DVAL`\
6759  `VAL`
6760 : The location into which the data value will be read. You cannot get
6761  CHARACTER data from a numeric variable or numeric data from a
6762  character variable. For numeric data, if the type of data differs
6763  from the netCDF variable type, type conversion will occur. (see
6764  [(netcdf)Type Conversion](netcdf.html#Type-Conversion) ‘Type
6765  Conversion’ in The NetCDF Users Guide).
6766 
6767 Errors
6768 ------
6769 
6770 NF\_GET\_VAR1\_ type returns the value NF\_NOERR if no errors occurred.
6771 Otherwise, the returned status indicates an error. Possible causes of
6772 errors include:
6773 
6774 - The variable ID is invalid for the specified netCDF dataset.
6775 - The specified indices were out of range for the rank of the
6776  specified variable. For example, a negative index or an index that
6777  is larger than the corresponding dimension length will cause an
6778  error.
6779 - The value is out of the range of values representable by the desired
6780  data type.
6781 - The specified netCDF is in define mode rather than data mode.
6782 - The specified netCDF ID does not refer to an open netCDF dataset.
6783 
6784 Example
6785 -------
6786 
6787 Here is an example using NF\_GET\_VAR1\_DOUBLE to get the (4,3,2)
6788 element of the variable named rh in an existing netCDF dataset named
6789 foo.nc. For simplicity in this example, we ame that we know that rh
6790 is dimensioned with lon, lat, and time, so we want to get the value of
6791 rh that corresponds to the fourth lon value, the third lat value, and
6792 the second time value:
6793 
6794  
6795 
6796 
6797 INCLUDE 'netcdf.inc'
6798  ...
6799 INTEGER STATUS, NCID
6800 INTEGER RHID ! variable ID
6801 INTEGER RHINDX(3) ! where to get value
6802 DOUBLE PRECISION RHVAL ! put it here
6803 DATA RHINDX /4, 3, 2/
6804  ...
6805 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
6806 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6807  ...
6808 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
6809 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6810 STATUS = NF_GET_VAR1_DOUBLE (NCID, RHID, RHINDX, RHVAL)
6811 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6812 
6813 
6814 6.25 NF\_GET\_VAR\_ type
6815 ------------------------
6816 
6817 The members of the NF\_GET\_VAR\_ type family of functions read all the
6818 values from a netCDF variable of an open netCDF dataset. This is the
6819 simplest interface to use for reading the value of a scalar variable or
6820 when all the values of a multidimensional variable can be read at once.
6821 The values are read into consecutive locations with the first dimension
6822 varying fastest. The netCDF dataset must be in data mode.
6823 
6824 Take care when using the simplest forms of this interface with record
6825 variables (variables that use the NF\_UNLIMITED dimension) when you
6826 don’t specify how many records are to be read. If you try to read all
6827 the values of a record variable into an array but there are more records
6828 in the file than you ame, more data will be read than you expect,
6829 which may cause a segmentation violation. To avoidch problems, it is
6830 better to use the NF\_GET\_VARA\_type interfaces for variables that use
6831 the NF\_UNLIMITED dimension. See [NF\_GET\_VARA\_
6832 type](#NF_005fGET_005fVARA_005f-type).
6833 
6834 Usage
6835 -----
6836 
6837  
6838 
6839 
6840 INTEGER FUNCTION NF_GET_VAR_TEXT (INTEGER NCID, INTEGER VARID,
6841  CHARACTER*(*) text)
6842 INTEGER FUNCTION NF_GET_VAR_INT1 (INTEGER NCID, INTEGER VARID,
6843  INTEGER*1 i1vals(*))
6844 INTEGER FUNCTION NF_GET_VAR_INT2 (INTEGER NCID, INTEGER VARID,
6845  INTEGER*2 i2vals(*))
6846 INTEGER FUNCTION NF_GET_VAR_INT (INTEGER NCID, INTEGER VARID,
6847  INTEGER ivals(*))
6848 INTEGER FUNCTION NF_GET_VAR_REAL (INTEGER NCID, INTEGER VARID,
6849  REAL rvals(*))
6850 INTEGER FUNCTION NF_GET_VAR_DOUBLE(INTEGER NCID, INTEGER VARID,
6851  DOUBLE dvals(*))
6852 INTEGER FUNCTION NF_GET_VAR (INTEGER NCID, INTEGER VARID,
6853  vals(*))
6854 
6855 
6856  `NCID`
6857 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6858 
6859  `VARID`
6860 : Variable ID.
6861 
6862  `TEXT`\
6863  `I1VALS`\
6864  `I2VALS`\
6865  `IVALS`\
6866  `RVALS`\
6867  `DVALS`\
6868  `VALS`
6869 : The block of data values to be read. The data should be of the type
6870  appropriate for the function called. You cannot read CHARACTER data
6871  from a numeric variable or numeric data from a text variable. For
6872  numeric data, if the type of data differs from the netCDF variable
6873  type, type conversion will occur (see [(netcdf)Type
6874  Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6875  in The NetCDF Users Guide).
6876 
6877 Errors
6878 ------
6879 
6880 NF\_GET\_VAR\_ type returns the value NF\_NOERR if no errors occurred.
6881 Otherwise, the returned status indicates an error. Possible causes of
6882 errors include:
6883 
6884 - The variable ID is invalid for the specified netCDF dataset.
6885 - One or more of the values are out of the range of values
6886  representable by the desired type.
6887 - The specified netCDF is in define mode rather than data mode.
6888 - The specified netCDF ID does not refer to an open netCDF dataset.
6889 
6890 Example
6891 -------
6892 
6893 Here is an example using NF\_GET\_VAR\_DOUBLE to read all the values of
6894 the variable named rh from an existing netCDF dataset named foo.nc. For
6895 simplicity in this example, we ame that we know that rh is
6896 dimensioned with lon and lat, and that there are ten lon values and five
6897 lat values.
6898 
6899  
6900 
6901 
6902 INCLUDE 'netcdf.inc'
6903  ...
6904 PARAMETER (LATS=5, LONS=10) ! dimension lengths
6905 INTEGER STATUS, NCID
6906 INTEGER RHID ! variable ID
6907 DOUBLE RHVALS(LONS, LATS)
6908  ...
6909 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
6910 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6911  ...
6912 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
6913 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6914 STATUS = NF_GET_VAR_DOUBLE (NCID, RHID, RHVALS)
6915 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
6916 
6917 
6918 6.26 NF\_GET\_VARA\_ type
6919 -------------------------
6920 
6921 The members of the NF\_GET\_VARA\_ type family of functions read an
6922 array of values from a netCDF variable of an open netCDF dataset. The
6923 array is specified by giving a corner and a vector of edge lengths. The
6924 values are read into consecutive locations with the first dimension
6925 varying fastest. The netCDF dataset must be in data mode.
6926 
6927 Usage
6928 -----
6929 
6930  
6931 
6932 
6933 INTEGER FUNCTION NF_GET_VARA_TEXT(INTEGER NCID, INTEGER VARID,
6934  INTEGER START(*), INTEGER COUNT(*),
6935  CHARACTER*(*) text)
6936 INTEGER FUNCTION NF_GET_VARA_INT1(INTEGER NCID, INTEGER VARID,
6937  INTEGER START(*), INTEGER COUNT(*),
6938  INTEGER*1 i1vals(*))
6939 INTEGER FUNCTION NF_GET_VARA_INT2(INTEGER NCID, INTEGER VARID,
6940  INTEGER START(*), INTEGER COUNT(*),
6941  INTEGER*2 i2vals(*))
6942 INTEGER FUNCTION NF_GET_VARA_INT (INTEGER NCID, INTEGER VARID,
6943  INTEGER START(*), INTEGER COUNT(*),
6944  INTEGER ivals(*))
6945 INTEGER FUNCTION NF_GET_VARA_REAL(INTEGER NCID, INTEGER VARID,
6946  INTEGER START(*), INTEGER COUNT(*),
6947  REAL rvals(*))
6948 INTEGER FUNCTION NF_GET_VARA_DOUBLE(INTEGER NCID, INTEGER VARID,
6949  INTEGER START(*), INTEGER COUNT(*),
6950  DOUBLE dvals(*))
6951 
6952 
6953  `NCID`
6954 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
6955 
6956  `VARID`
6957 : Variable ID.
6958 
6959  `START`
6960 : A vector of integers specifying the index in the variable where the
6961  first of the data values will be read. The indices are relative to
6962  1, so for example, the first data value of a variable would have
6963  index (1, 1, ..., 1). The length of START must be the same as the
6964  number of dimensions of the specified variable. The elements of
6965  START correspond, in order, to the variable’s dimensions. Hence, if
6966  the variable is a record variable, the last index would correspond
6967  to the starting record number for reading the data values.
6968 
6969  `COUNT`
6970 : A vector of integers specifying the edge lengths along each
6971  dimension of the block of data values to be read. To read a single
6972  value, for example, specify COUNT as (1, 1, ..., 1). The length of
6973  COUNT is the number of dimensions of the specified variable. The
6974  elements of COUNT correspond, in order, to the variable’s
6975  dimensions. Hence, if the variable is a record variable, the last
6976  element of COUNT corresponds to a count of the number of records to
6977  read.
6978 
6979  Note: setting any element of the count array to zero causes the
6980  function to exit without error, and without doing anything.
6981 
6982  `text`\
6983  `i1vals`\
6984  `i2vals`\
6985  `ivals`\
6986  `rvals`\
6987  `dvals`
6988 : The block of data values to be read. The data should be of the type
6989  appropriate for the function called. You cannot read CHARACTER data
6990  from a numeric variable or numeric data from a text variable. For
6991  numeric data, if the type of data differs from the netCDF variable
6992  type, type conversion will occur (see [(netcdf)Type
6993  Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
6994  in The NetCDF Users Guide).
6995 
6996 Errors
6997 ------
6998 
6999 NF\_GET\_VARA\_ type returns the value NF\_NOERR if no errors occurred.
7000 Otherwise, the returned status indicates an error. Possible causes of
7001 errors include:
7002 
7003 - The variable ID is invalid for the specified netCDF dataset.
7004 - The specified corner indices were out of range for the rank of the
7005  specified variable. For example, a negative index or an index that
7006  is larger than the corresponding dimension length will cause an
7007  error.
7008 - The specified edge lengths added to the specified corner would have
7009  referenced data out of range for the rank of the specified variable.
7010  For example, an edge length that is larger than the corresponding
7011  dimension length minus the corner index will cause an error.
7012 - One or more of the values are out of the range of values
7013  representable by the desired type.
7014 - The specified netCDF is in define mode rather than data mode.
7015 - The specified netCDF ID does not refer to an open netCDF dataset.
7016 
7017 Example
7018 -------
7019 
7020 Here is an example using NF\_GET\_VARA\_DOUBLE to read all the values of
7021 the variable named rh from an existing netCDF dataset named foo.nc. For
7022 simplicity in this example, we ame that we know that rh is
7023 dimensioned with lon, lat, and time, and that there are ten lon values,
7024 five lat values, and three time values.
7025 
7026  
7027 
7028 
7029 INCLUDE 'netcdf.inc'
7030  ...
7031 PARAMETER (NDIMS=3) ! number of dimensions
7032 PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
7033 INTEGER STATUS, NCID
7034 INTEGER RHID ! variable ID
7035 INTEGER START(NDIMS), COUNT(NDIMS)
7036 DOUBLE RHVALS(LONS, LATS, TIMES)
7037 DATA START /1, 1, 1/ ! start at first value
7038 DATA COUNT /LONS, LATS, TIMES/ ! get all the values
7039  ...
7040 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
7041 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7042  ...
7043 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7044 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7045 STATUS = NF_GET_VARA_DOUBLE (NCID, RHID, START, COUNT, RHVALS)
7046 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7047 
7048 
7049 6.27 NF\_GET\_VARS\_ type
7050 -------------------------
7051 
7052 The NF\_GET\_VARS\_ type family of functions read absampled (strided)
7053 array of values from a netCDF variable of an open netCDF
7054 dataset. Thebsampled array is specified by giving a corner, a
7055 vector of edge lengths, and a stride vector. The values are read with
7056 the first dimension of the netCDF variable varying fastest. The netCDF
7057 dataset must be in data mode.
7058 
7059 Usage
7060 -----
7061 
7062  
7063 
7064 
7065 INTEGER FUNCTION NF_GET_VARS_TEXT (INTEGER NCID, INTEGER VARID,
7066  INTEGER START(*), INTEGER COUNT(*),
7067  INTEGER STRIDE(*),CHARACTER*(*) text)
7068 INTEGER FUNCTION NF_GET_VARS_INT1 (INTEGER NCID, INTEGER VARID,
7069  INTEGER START(*), INTEGER COUNT(*),
7070  INTEGER STRIDE(*),INTEGER*1 i1vals(*))
7071 INTEGER FUNCTION NF_GET_VARS_INT2 (INTEGER NCID, INTEGER VARID,
7072  INTEGER START(*), INTEGER COUNT(*),
7073  INTEGER STRIDE(*),INTEGER*2 i2vals(*))
7074 INTEGER FUNCTION NF_GET_VARS_INT (INTEGER NCID, INTEGER VARID,
7075  INTEGER START(*), INTEGER COUNT(*),
7076  INTEGER STRIDE(*), INTEGER ivals(*))
7077 INTEGER FUNCTION NF_GET_VARS_REAL (INTEGER NCID, INTEGER VARID,
7078  INTEGER START(*), INTEGER COUNT(*),
7079  INTEGER STRIDE(*), REAL rvals(*))
7080 INTEGER FUNCTION NF_GET_VARS_DOUBLE(INTEGER NCID, INTEGER VARID,
7081  INTEGER START(*), INTEGER COUNT(*),
7082  INTEGER STRIDE(*), DOUBLE dvals(*))
7083 
7084 
7085  `NCID`
7086 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7087 
7088  `VARID`
7089 : Variable ID.
7090 
7091  `START`
7092 : A vector of integers specifying the index in the variable from which
7093  the first of the data values will be read. The indices are relative
7094  to 1, so for example, the first data value of a variable would have
7095  index (1, 1, ..., 1). The elements of START correspond, in order, to
7096  the variable’s dimensions. Hence, if the variable is a record
7097  variable, the last index would correspond to the starting record
7098  number for reading the data values.
7099 
7100  `COUNT`
7101 : A vector of integers specifying the number of indices selected along
7102  each dimension. To read a single value, for example, specify COUNT
7103  as (1, 1, ..., 1). The elements of COUNT correspond, in order, to
7104  the variable’s dimensions. Hence, if the variable is a record
7105  variable, the last element of COUNT corresponds to a count of the
7106  number of records to read.
7107 
7108  Note: setting any element of the count array to zero causes the
7109  function to exit without error, and without doing anything.
7110 
7111  `STRIDE`
7112 : A vector of integers specifying, for each dimension, the interval
7113  between selected indices or the value 0. The elements of the vector
7114  correspond, in order, to the variable’s dimensions. A value of 1
7115  accesses adjacent values of the netCDF variable in the corresponding
7116  dimension; a value of 2 accesses every other value of the netCDF
7117  variable in the corresponding dimension; and so on. A 0 argument is
7118  treated as (1, 1, ..., 1).
7119 
7120  `text`\
7121  `i1vals`\
7122  `i2vals`\
7123  `ivals`\
7124  `rvals`\
7125  `dvals`
7126 : The block of data values to be read. The data should be of the type
7127  appropriate for the function called. You cannot read CHARACTER data
7128  from a numeric variable or numeric data from a text variable. For
7129  numeric data, if the type of data differs from the netCDF variable
7130  type, type conversion will occur (see [(netcdf)Type
7131  Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
7132  in The NetCDF Users Guide).
7133 
7134 Errors
7135 ------
7136 
7137 NF\_GET\_VARS\_ type returns the value NF\_NOERR if no errors occurred.
7138 Otherwise, the returned status indicates an error. Possible causes of
7139 errors include:
7140 
7141 - The variable ID is invalid for the specified netCDF dataset.
7142 - The specified start, count and stride generate an index which is out
7143  of range.
7144 - One or more of the values are out of the range of values
7145  representable by the desired type.
7146 - The specified netCDF is in define mode rather than data mode.
7147 - The specified netCDF ID does not refer to an open netCDF dataset.
7148 
7149 Example
7150 -------
7151 
7152 Here is an example using NF\_GET\_VARS\_DOUBLE to read every other value
7153 in each dimension of the variable named rh from an existing netCDF
7154 dataset named foo.nc. Values are assigned, using the same dimensional
7155 strides, to a 2-parameter array. For simplicity in this example, we
7156 ame that we know that rh is dimensioned with lon, lat, and time, and
7157 that there are ten lon values, five lat values, and three time values.
7158 
7159  
7160 
7161 
7162 INCLUDE 'netcdf.inc'
7163  ...
7164 PARAMETER (NDIMS=3) ! number of dimensions
7165 PARAMETER (TIMES=3, LATS=5, LONS=10) ! dimension lengths
7166 INTEGER STATUS, NCID
7167 INTEGER RHID ! variable ID
7168 INTEGER START(NDIMS), COUNT(NDIMS), STRIDE(NDIMS)
7169 DOUBLE DATA(LONS, LATS, TIMES)
7170 DATA START /1, 1, 1/ ! start at first value
7171 DATA COUNT /LONS, LATS, TIMES/
7172 DATA STRIDE /2, 2, 2/
7173  ...
7174 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
7175 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7176  ...
7177 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7178 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7179 STATUS = NF_GET_VARS_DOUBLE(NCID,RHID,START,COUNT,STRIDE,DATA(1,1,1))
7180 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7181 
7182 
7183 6.28 NF\_GET\_VARM\_ type
7184 -------------------------
7185 
7186 The NF\_GET\_VARM\_ type family of functions reads a mapped array
7187 section of values from a netCDF variable of an open netCDF dataset. The
7188 mapped array is specified by giving a corner, a vector of edge
7189 lengths, a stride vector, and an index mapping vector. The index mapping
7190 vector is a vector of integers that specifies the mapping between the
7191 dimensions of a netCDF variable and the in-memory structure of the
7192 internal data array. No amptions are made about the ordering or
7193 length of the dimensions of the data array. The netCDF dataset must be
7194 in data mode.
7195 
7196 Usage
7197 -----
7198 
7199  
7200 
7201 
7202 INTEGER FUNCTION NF_GET_VARM_TEXT (INTEGER NCID, INTEGER VARID,
7203  INTEGER START(*), INTEGER COUNT(*),
7204  INTEGER STRIDE(*), INTEGER IMAP(*),
7205  CHARACTER*(*) text)
7206 INTEGER FUNCTION NF_GET_VARM_INT1 (INTEGER NCID, INTEGER VARID,
7207  INTEGER START(*), INTEGER COUNT(*),
7208  INTEGER STRIDE(*), INTEGER IMAP(*),
7209  INTEGER*1 i1vals(*))
7210 INTEGER FUNCTION NF_GET_VARM_INT2 (INTEGER NCID, INTEGER VARID,
7211  INTEGER START(*), INTEGER COUNT(*),
7212  INTEGER STRIDE(*), INTEGER IMAP(*),
7213  INTEGER*2 i2vals(*))
7214 INTEGER FUNCTION NF_GET_VARM_INT (INTEGER NCID, INTEGER VARID,
7215  INTEGER START(*), INTEGER COUNT(*),
7216  INTEGER STRIDE(*), INTEGER IMAP(*),
7217  INTEGER ivals(*))
7218 INTEGER FUNCTION NF_GET_VARM_REAL (INTEGER NCID, INTEGER VARID,
7219  INTEGER START(*), INTEGER COUNT(*),
7220  INTEGER STRIDE(*), INTEGER IMAP(*),
7221  REAL rvals(*))
7222 INTEGER FUNCTION NF_GET_VARM_DOUBLE(INTEGER NCID, INTEGER VARID,
7223  INTEGER START(*), INTEGER COUNT(*),
7224  INTEGER STRIDE(*), INTEGER IMAP(*),
7225  DOUBLE dvals(*))
7226 
7227 
7228  `NCID`
7229 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7230 
7231  `VARID`
7232 : Variable ID.
7233 
7234  `START`
7235 : A vector of integers specifying the index in the variable from which
7236  the first of the data values will be read. The indices are relative
7237  to 1, so for example, the first data value of a variable would have
7238  index (1, 1, ..., 1). The elements of START correspond, in order, to
7239  the variable’s dimensions. Hence, if the variable is a record
7240  variable, the last index would correspond to the starting record
7241  number for reading the data values.
7242 
7243  `COUNT`
7244 : A vector of integers specifying the number of indices selected along
7245  each dimension. To read a single value, for example, specify COUNT
7246  as (1, 1, ..., 1). The elements of COUNT correspond, in order, to
7247  the variable’s dimensions. Hence, if the variable is a record
7248  variable, the last element of COUNT corresponds to a count of the
7249  number of records to read.
7250 
7251  Note: setting any element of the count array to zero causes the
7252  function to exit without error, and without doing anything.
7253 
7254  `STRIDE`
7255 : A vector of integers specifying, for each dimension, the interval
7256  between selected indices or the value 0. The elements of the vector
7257  correspond, in order, to the variable’s dimensions. A value of 1
7258  accesses adjacent values of the netCDF variable in the corresponding
7259  dimension; a value of 2 accesses every other value of the netCDF
7260  variable in the corresponding dimension; and so on. A 0 argument is
7261  treated as (1, 1, ..., 1).
7262 
7263  `IMAP`
7264 : A vector of integers that specifies the mapping between the
7265  dimensions of a netCDF variable and the in-memory structure of the
7266  internal data array. IMAP(1) gives the distance between elements of
7267  the internal array corresponding to the most rapidly varying
7268  dimension of the netCDF variable. IMAP(N) (where N is the rank of
7269  the netCDF variable) gives the distance between elements of the
7270  internal array corresponding to the most slowly varying dimension of
7271  the netCDF variable. Intervening IMAP elements correspond to other
7272  dimensions of the netCDF variable in the obvious way. Distances
7273  between elements are specified in units of elements (the distance
7274  between internal elements that occupy adjacent memory locations is 1
7275  and not the element’s byte-length as in netCDF 2).
7276 
7277  `text`\
7278  `i1vals`\
7279  `i2vals`\
7280  `ivals`\
7281  `rvals`\
7282  `dvals`
7283 : The block of data values to be read. The data should be of the type
7284  appropriate for the function called. You cannot read CHARACTER data
7285  from a numeric variable or numeric data from a text variable. For
7286  numeric data, if the type of data differs from the netCDF variable
7287  type, type conversion will occur (see [(netcdf)Type
7288  Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
7289  in The NetCDF Users Guide).
7290 
7291 Errors
7292 ------
7293 
7294 NF\_GET\_VARM\_ type returns the value NF\_NOERR if no errors occurred.
7295 Otherwise, the returned status indicates an error. Possible causes of
7296 errors include:
7297 
7298 - The variable ID is invalid for the specified netCDF dataset.
7299 - The specified START, COUNT, and STRIDE generate an index which is
7300  out of range. Note that no error checking is possible on the imap
7301  vector.
7302 - One or more of the values are out of the range of values
7303  representable by the desired type.
7304 - The specified netCDF is in define mode rather than data mode.
7305 - The specified netCDF ID does not refer to an open netCDF dataset.
7306 
7307 Example
7308 -------
7309 
7310 The following IMAP vector maps in the trivial way a 2x3x4 netCDF
7311 variable and an internal array of the same shape:
7312 
7313  
7314 
7315 
7316 REAL A(2,3,4) ! same shape as netCDF variable
7317 INTEGER IMAP(3)
7318 DATA IMAP /1, 2, 6/ ! netCDF dimension inter-element distance
7319  ! ---------------- ----------------------
7320  ! most rapidly varying 1
7321  ! intermediate 2 (=IMAP(1)*2)
7322  ! most slowly varying 6 (=IMAP(2)*3)
7323 
7324 
7325 Using the IMAP vector above with NF\_GET\_VARM\_REAL obtains the same
7326 rlt as simply using NF\_GET\_VAR\_REAL.
7327 
7328 Here is an example of using NF\_GET\_VARM\_REAL to transpose a netCDF
7329 variable named rh which is described by the FORTRAN declaration REAL
7330 RH(4,6) (note the size and order of the dimensions):
7331 
7332  
7333 
7334 
7335 INCLUDE 'netcdf.inc'
7336  ...
7337 PARAMETER (NDIM=2) ! rank of netCDF variable
7338 INTEGER NCID ! netCDF dataset ID
7339 INTEGER STATUS ! return code
7340 INTEGER RHID ! variable ID
7341 INTEGER START(NDIM) ! netCDF variable start point
7342 INTEGER COUNT(NDIM) ! size of internal array
7343 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
7344 INTEGER IMAP(NDIM) ! internal array inter-element distances
7345 REAL RH(6,4) ! note transposition of netCDF variable dimensions
7346 DATA START /1, 1/ ! start at first netCDF variable element
7347 DATA COUNT /4, 6/ ! entire netCDF variable; order corresponds
7348  ! to netCDF variable -- not internal array
7349 DATA STRIDE /1, 1/ ! sample every netCDF element
7350 DATA IMAP /6, 1/ ! would be /1, 4/ if not transposing
7351  ...
7352 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
7353 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7354  ...
7355 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
7356 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7357  ...
7358 STATUS = NF_GET_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
7359 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7360 
7361 
7362 Here is another example of using NF\_GET\_VARM\_REAL to simultaneously
7363 transpose andbsample the same netCDF variable, by accessing every
7364 other point of the netCDF variable:
7365 
7366  
7367 
7368 
7369 INCLUDE 'netcdf.inc'
7370  ...
7371 PARAMETER (NDIM=2) ! rank of netCDF variable
7372 INTEGER NCID ! netCDF dataset ID
7373 INTEGER STATUS ! return code
7374 INTEGER RHID ! variable ID
7375 INTEGER START(NDIM) ! netCDF variable start point
7376 INTEGER COUNT(NDIM) ! size of internal array
7377 INTEGER STRIDE(NDIM) ! netCDF variablebsampling intervals
7378 INTEGER IMAP(NDIM) ! internal array inter-element distances
7379 REAL RH(3,2) ! note transposition of bsampled) dimensions
7380 DATA START /1, 1/ ! start at first netCDF variable value
7381 DATA COUNT /2, 3/ ! order of bsampled) dimensions corresponds
7382  ! to netCDF variable -- not internal array
7383 DATA STRIDE /2, 2/ ! sample every other netCDF element
7384 DATA IMAP /3, 1/ ! would be `1, 2' if not transposing
7385  ...
7386 STATUS = NF_OPEN('foo.nc', NF_NOWRITE, NCID)
7387 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7388  ...
7389 STATUS = NF_INQ_VARID(NCID, 'rh', RHID)
7390 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7391  ...
7392 STATUS = NF_GET_VARM_REAL(NCID, RHID, START, COUNT, STRIDE, IMAP, RH)
7393 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7394 
7395 
7396 6.29 Reading and Writing Character String Values
7397 ------------------------------------------------
7398 
7399 Character strings are not a primitive netCDF external data type, in part
7400 because FORTRAN does notpport the abstraction of variable-length
7401 character strings (the FORTRAN LEN function returns the static length of
7402 a character string, not its dynamic length). As a rlt, a character
7403 string cannot be written or read as a single object in the netCDF
7404 interface. Instead, a character string must be treated as an array of
7405 characters, and array access must be used to read and write character
7406 strings as variable data in netCDF datasets. Furthermore,
7407 variable-length strings are notpported by the netCDF interface except
7408 by convention; for example, you may treat a zero byte as terminating a
7409 character string, but you must explicitly specify the length of strings
7410 to be read from and written to netCDF variables.
7411 
7412 Character strings as attribute values are easier to use, since the
7413 strings are treated as a single unit for access. However, the value of a
7414 character-string attribute is still an array of characters with an
7415 explicit length that must be specified when the attribute is defined.
7416 
7417 When you define a variable that will have character-string values, use a
7418 character-position dimension as the most quickly varying dimension for
7419 the variable (the first dimension for the variable in FORTRAN). The
7420 length of the character-position dimension will be the maximum string
7421 length of any value to be stored in the character-string variable. Space
7422 for maximum-length strings will be allocated in the disk representation
7423 of character-string variables whether you use the space or not. If two
7424 or more variables have the same maximum length, the same
7425 character-position dimension may be used in defining the variable
7426 shapes.
7427 
7428 To write a character-string value into a character-string variable, use
7429 either entire variable access or array access. The latter requires that
7430 you specify both a corner and a vector of edge lengths. The
7431 character-position dimension at the corner should be one for FORTRAN. If
7432 the length of the string to be written is n, then the vector of edge
7433 lengths will specify n in the character-position dimension, and one for
7434 all the other dimensions:(n, 1, 1, ..., 1).
7435 
7436 In FORTRAN, fixed-length strings may be written to a netCDF dataset
7437 without a terminating character, to save space. Variable-length strings
7438 should follow the C convention of writing strings with a terminating
7439 zero byte so that the intended length of the string can be determined
7440 when it is later read by either C or FORTRAN programs.
7441 
7442 The FORTRAN interface for reading and writing strings requires the use
7443 of different functions for accessing string values and numeric values,
7444 because standard FORTRAN does not permit the same formal parameter to be
7445 used for both character values and numeric values. An additional
7446 argument, specifying the declared length of the character string passed
7447 as a value, is required for NF\_PUT\_VARA\_TEXT and NF\_GET\_VARA\_TEXT.
7448 The actual length of the string is specified as the value of the
7449 edge-length vector corresponding to the character-position dimension.
7450 
7451 Here is an example that defines a record variable, tx, for character
7452 strings and stores a character-string value into the third record using
7453 NF\_PUT\_VARA\_TEXT. In this example, we ame the string variable and
7454 data are to be added to an existing netCDF dataset named foo.nc that
7455 already has an unlimited record dimension time.
7456 
7457  
7458 
7459 
7460 INCLUDE 'netcdf.inc'
7461  ...
7462 INTEGER TDIMS, TXLEN
7463 PARAMETER (TDIMS=2) ! number of TX dimensions
7464 PARAMETER (TXLEN = 15) ! length of example string
7465 INTEGER NCID
7466 INTEGER CHID ! char position dimension id
7467 INTEGER TIMEID ! record dimension id
7468 INTEGER TXID ! variable ID
7469 INTEGER TXDIMS(TDIMS) ! variable shape
7470 INTEGER TSTART(TDIMS), TCOUNT(TDIMS)
7471 CHARACTER*40 TXVAL ! max length 40
7472 DATA TXVAL /'example string'/
7473  ...
7474 TXVAL(TXLEN:TXLEN) = CHAR(0) ! null terminate
7475  ...
7476 STATUS = NF_OPEN('foo.nc', NF_WRITE, NCID)
7477 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7478 STATUS = NF_REDEF(NCID) ! enter define mode
7479 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7480  ...
7481 ! define character-position dimension for strings of max length 40
7482 STATUS = NF_DEF_DIM(NCID, "chid", 40, CHID)
7483 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7484  ...
7485 ! define a character-string variable
7486 TXDIMS(1) = CHID ! character-position dimension first
7487 TXDIMS(2) = TIMEID
7488 STATUS = NF_DEF_VAR(NCID, "tx", NF_CHAR, TDIMS, TXDIMS, TXID)
7489 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7490  ...
7491 STATUS = NF_ENDDEF(NCID) ! leave define mode
7492 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7493  ...
7494 ! write txval into tx netCDF variable in record 3
7495 TSTART(1) = 1 ! start at beginning of variable
7496 TSTART(2) = 3 ! record number to write
7497 TCOUNT(1) = TXLEN ! number of chars to write
7498 TCOUNT(2) = 1 ! only write one record
7499 STATUS = NF_PUT_VARA_TEXT (NCID, TXID, TSTART, TCOUNT, TXVAL)
7500 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7501 
7502 
7503 6.30 Fill Values
7504 ----------------
7505 
7506 What happens when you try to read a value that was never written in an
7507 open netCDF dataset? You might expect that this should always be an
7508 error, and that you should get an error message or an error status
7509 returned. You do get an error if you try to read data from a netCDF
7510 dataset that is not open for reading, if the variable ID is invalid for
7511 the specified netCDF dataset, or if the specified indices are not
7512 properly within the range defined by the dimension lengths of the
7513 specified variable. Otherwise, reading a value that was not written
7514 returns a special fill value used to fill in any undefined values when a
7515 netCDF variable is first written.
7516 
7517 You may ignore fill values and use the entire range of a netCDF external
7518 data type, but in this case you should makere you write all data
7519 values before reading them. If you know you will be writing all the data
7520 before reading it, you can specify that no prefilling of variables with
7521 fill values will occur by calling NF\_SET\_FILL before writing. This may
7522 provide a significant performance gain for netCDF writes.
7523 
7524 The variable attribute \_FillValue may be used to specify the fill value
7525 for a variable. Their are default fill values for each type, defined in
7526 the include file netcdf.inc: NF\_FILL\_CHAR, NF\_FILL\_INT1 (same as
7527 NF\_FILL\_BYTE), NF\_FILL\_INT2 (same as NF\_FILL\_SHORT),
7528 NF\_FILL\_INT, NF\_FILL\_REAL (same as NF\_FILL\_FLOAT), and
7529 NF\_FILL\_DOUBLE.
7530 
7531 The netCDF byte and character types have different default fill values.
7532 The default fill value for characters is the zero byte, a useful value
7533 for detecting the end of variable-length C character strings. If you
7534 need a fill value for a byte variable, it is recommended that you
7535 explicitly define an appropriate \_FillValue attribute, as generic
7536 utilitiesch as ncdump will not ame a default fill value for byte
7537 variables.
7538 
7539 Type conversion for fill values is identical to type conversion for
7540 other values: attempting to convert a value from one type to another
7541 type that can’t represent the value rlts in a range error. Such
7542 errors may occur on writing or reading values from a larger type ch
7543 as double) to a smaller type ch as float), if the fill value for the
7544 larger type cannot be represented in the smaller type.
7545 
7546 6.31 NF\_RENAME\_VAR
7547 --------------------
7548 
7549 The function NF\_RENAME\_VAR changes the name of a netCDF variable in an
7550 open netCDF dataset. If the new name is longer than the old name, the
7551 netCDF dataset must be in define mode. You cannot rename a variable to
7552 have the name of any existing variable.
7553 
7554 Usage
7555 -----
7556 
7557  
7558 
7559 
7560 INTEGER FUNCTION NF_RENAME_VAR (INTEGER NCID, INTEGER VARID,
7561  CHARACTER*(*) NEWNAM)
7562 
7563 
7564  `NCID`
7565 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7566 
7567  `VARID`
7568 : Variable ID.
7569 
7570  `NAME`
7571 : New name for the specified variable.
7572 
7573 Errors
7574 ------
7575 
7576 NF\_RENAME\_VAR returns the value NF\_NOERR if no errors occurred.
7577 Otherwise, the returned status indicates an error. Possible causes of
7578 errors include:
7579 
7580 - The new name is in use as the name of another variable.
7581 - The variable ID is invalid for the specified netCDF dataset.
7582 - The specified netCDF ID does not refer to an open netCDF dataset.
7583 
7584 Example
7585 -------
7586 
7587 Here is an example using NF\_RENAME\_VAR to rename the variable rh to
7588 rel\_hum in an existing netCDF dataset named foo.nc:
7589 
7590  
7591 
7592 
7593 INCLUDE 'netcdf.inc'
7594  ...
7595 INTEGER STATUS, NCID
7596 INTEGER RHID ! variable ID
7597  ...
7598 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
7599 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7600  ...
7601 STATUS = NF_REDEF (NCID) ! enter definition mode
7602 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7603 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7604 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7605 STATUS = NF_RENAME_VAR (NCID, RHID, 'rel_hum')
7606 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7607 STATUS = NF_ENDDEF (NCID) ! leave definition mode
7608 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7609 
7610 
7611 
7612 6.32 Change between Collective and Independent Parallel Access: NF\_VAR\_PAR\_ACCESS
7613 ------------------------------------------------------------------------------------
7614 
7615 The function NF\_VAR\_PAR\_ACCESS changes whether read/write operations
7616 on a parallel file system are performed collectively or independently
7617 (the default) on the variable. This function can only be called if the
7618 file was created with NF\_CREATE\_PAR (see
7619 [NF\_CREATE\_PAR](#NF_005fCREATE_005fPAR)) or opened with NF\_OPEN\_PAR
7620 (see [NF\_OPEN\_PAR](#NF_005fOPEN_005fPAR)).
7621 
7622 This function is only available if the netCDF library was built with a
7623 HDF5 library for which –enable-parallel was used, and which was linked
7624 (like HDF5) to MPI libraries.
7625 
7626 Calling this function affects only the open file - information about
7627 whether a variable is to be accessed collectively or independently is
7628 not written to the data file. Every time you open a file on a parallel
7629 file system, all variables default to independent operations. The change
7630 a variable to collective lasts only as long as that file is open.
7631 
7632 The variable can be changed from collective to independent, and back, as
7633 often as desired.
7634 
7635 Usage
7636 -----
7637 
7638  
7639 
7640 
7641 INTEGER NF_VAR_PAR_ACCESS(INTEGER NCID, INTEGER VARID, INTEGER ACCESS);
7642 
7643 
7644  `NCID`
7645 : NetCDF ID, from a previous call to NF\_OPEN\_PAR (see
7646  [NF\_OPEN\_PAR](#NF_005fOPEN_005fPAR)) or NF\_CREATE\_PAR (see
7647  [NF\_CREATE\_PAR](#NF_005fCREATE_005fPAR)).
7648 
7649  `varid`
7650 : Variable ID.
7651 
7652  `access`
7653 : NF\_INDEPENDENT to set this variable to independent operations.
7654  NF\_COLLECTIVE to set it to collective operations.
7655 
7656 Return Values
7657 -------------
7658 
7659  `NF_NOERR`
7660 : No error.
7661 
7662  `NF_ENOTVAR`
7663 : No variable found.
7664 
7665  `NF_ENOTNC4`
7666 : Not a netCDF-4 file.
7667 
7668  `NF_NOPAR`
7669 : File not opened for parallel access.
7670 
7671 Example
7672 -------
7673 
7674 This example comes from test program nf\_test/ftst\_parallel.F. For this
7675 test to be run, netCDF must have been built with a parallel-enabled
7676 HDF5, and –enable-parallel-tests must have been used when configuring
7677 netcdf.
7678 
7679  
7680 
7681 
7682  retval = nf_var_par_access(ncid, varid, nf_collective)
7683  if (retval .ne. nf_noerr) stop 2
7684 
7685 
7686 
7687 7. Attributes
7688 =============
7689 
7690 7.1 Attributes Introduction
7691 ---------------------------
7692 
7693 Attributes may be associated with each netCDF variable to specifych
7694 properties as units, special values, maximum and minimum valid values,
7695 scaling factors, and offsets. Attributes for a netCDF dataset are
7696 defined when the dataset is first created, while the netCDF dataset is
7697 in define mode. Additional attributes may be added later by reentering
7698 define mode. A netCDF attribute has a netCDF variable to which it is
7699 assigned, a name, a type, a length, and a sequence of one or more
7700 values. An attribute is designated by its variable ID and name. When an
7701 attribute name is not known, it may be designated by its variable ID and
7702 number in order to determine its name, using the function
7703 NF\_INQ\_ATTNAME.
7704 
7705 The attributes associated with a variable are typically defined
7706 immediately after the variable is created, while still in define mode.
7707 The data type, length, and value of an attribute may be changed even
7708 when in data mode, as long as the changed attribute requires no more
7709 space than the attribute as originally defined.
7710 
7711 It is also possible to have attributes that are not associated with any
7712 variable. These are called global attributes and are identified by using
7713 NF\_GLOBAL as a variable pseudo-ID. Global attributes are ally
7714 related to the netCDF dataset as a whole and may be used for purposes
7715 such as providing a title or processing history for a netCDF dataset.
7716 
7717 Attributes are much more useful when they follow established community
7718 conventions. See [(netcdf)Attribute
7719 Conventions](netcdf.html#Attribute-Conventions) ‘Attribute
7720 Conventions’ in The NetCDF Users Guide.
7721 
7722 Operationspported on attributes are:
7723 
7724 - Create an attribute, given its variable ID, name, data type, length,
7725  and value.
7726 - Get attribute’s data type and length from its variable ID and name.
7727 - Get attribute’s value from its variable ID and name.
7728 - Copy attribute from one netCDF variable to another.
7729 - Get name of attribute from its number.
7730 - Rename an attribute.
7731 - Delete an attribute.
7732 
7733 7.2 NF\_PUT\_ATT\_ type
7734 -----------------------
7735 
7736 The function NF\_PUT\_ATT\_ type adds or changes a variable attribute or
7737 global attribute of an open netCDF dataset. If this attribute is new, or
7738 if the space required to store the attribute is greater than before, the
7739 netCDF dataset must be in define mode.
7740 
7741 Usage
7742 -----
7743 
7744 Although it’s possible to create attributes of all types, text and
7745 double attributes are adequate for most purposes.
7746 
7747  
7748 
7749 
7750 INTEGER FUNCTION NF_PUT_ATT_TEXT (INTEGER NCID, INTEGER VARID,
7751  CHARACTER*(*) NAME, INTEGER LEN,
7752  CHARACTER*(*) TEXT)
7753 INTEGER FUNCTION NF_PUT_ATT_INT1 (INTEGER NCID, INTEGER VARID,
7754  CHARACTER*(*) NAME, INTEGER XTYPE,
7755  LEN, INTEGER*1 I1VALS(*))
7756 INTEGER FUNCTION NF_PUT_ATT_INT2 (INTEGER NCID, INTEGER VARID,
7757  CHARACTER*(*) NAME, INTEGER XTYPE,
7758  LEN, INTEGER*2 I2VALS(*))
7759 INTEGER FUNCTION NF_PUT_ATT_INT (INTEGER NCID, INTEGER VARID,
7760  CHARACTER*(*) NAME, INTEGER XTYPE,
7761  LEN, INTEGER IVALS(*))
7762 INTEGER FUNCTION NF_PUT_ATT_REAL (INTEGER NCID, INTEGER VARID,
7763  CHARACTER*(*) NAME, INTEGER XTYPE,
7764  LEN, REAL RVALS(*))
7765 INTEGER FUNCTION NF_PUT_ATT_DOUBLE(INTEGER NCID, INTEGER VARID,
7766  CHARACTER*(*) NAME, INTEGER XTYPE,
7767  LEN, DOUBLE DVALS(*))
7768 INTEGER FUNCTION NF_PUT_ATT (INTEGER NCID, INTEGER VARID,
7769  CHARACTER*(*) NAME, INTEGER XTYPE,
7770  LEN, * VALS(*))
7771 
7772 
7773  `NCID`
7774 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7775 
7776  `VARID`
7777 : Variable ID of the variable to which the attribute will be assigned
7778  or NF\_GLOBAL for a global attribute.
7779 
7780  `NAME`
7781 : Attribute name. Attribute name conventions are amed by some
7782  netCDF generic applications, e.g., ‘units’ as the name for a string
7783  attribute that gives the units for a netCDF variable. See
7784  [(netcdf)Attribute Conventions](netcdf.html#Attribute-Conventions)
7785  ‘Attribute Conventions’ in The NetCDF Users Guide.
7786 
7787  `XTYPE`
7788 : One of the set of predefined netCDF external data types. The type of
7789  this parameter, NF\_TYPE, is defined in the netCDF header file. The
7790  valid netCDF external data types are NF\_BYTE, NF\_CHAR, NF\_SHORT,
7791  NF\_INT, NF\_FLOAT, and NF\_DOUBLE. Although it’s possible to create
7792  attributes of all types, NF\_CHAR and NF\_DOUBLE attributes are
7793  adequate for most purposes.
7794 
7795  `LEN`
7796 : Number of values provided for the attribute.
7797 
7798  `TEXT`\
7799  `I1VALS`\
7800  `I2VALS`\
7801  `IVALS`\
7802  `RVALS`\
7803  `DVALS`\
7804  `VALS`
7805 : An array of LEN attribute values. The data should be of a type
7806  appropriate for the function called. You cannot write CHARACTER data
7807  into a numeric attribute or numeric data into a text attribute. For
7808  numeric data, if the type of data differs from the attribute type,
7809  type conversion will occur See [(netcdf)Type
7810  Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
7811  in The NetCDF Users Guide.
7812 
7813 Errors
7814 ------
7815 
7816 NF\_PUT\_ATT\_ type returns the value NF\_NOERR if no errors occurred.
7817 Otherwise, the returned status indicates an error. Possible causes of
7818 errors include:
7819 
7820 - The variable ID is invalid for the specified netCDF dataset.
7821 - The specified netCDF type is invalid.
7822 - The specified length is negative.
7823 - The specified open netCDF dataset is in data mode and the specified
7824  attribute would expand.
7825 - The specified open netCDF dataset is in data mode and the specified
7826  attribute does not already exist.
7827 - The specified netCDF ID does not refer to an open netCDF dataset.
7828 - The number of attributes for this variable exceeds NF\_MAX\_ATTRS.
7829 
7830 Example
7831 -------
7832 
7833 Here is an example using NF\_PUT\_ATT\_DOUBLE to add a variable
7834 attribute named valid\_range for a netCDF variable named rh and a global
7835 attribute named title to an existing netCDF dataset named foo.nc:
7836 
7837  
7838 
7839 
7840 INCLUDE 'netcdf.inc'
7841  ...
7842 INTEGER STATUS, NCID
7843 INTEGER RHID ! variable ID
7844 DOUBLE RHRNGE(2)
7845 DATA RHRNGE /0.0D0, 100.0D0/
7846  ...
7847 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
7848 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7849  ...
7850 STATUS = NF_REDEF (NCID) ! enter define mode
7851 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7852 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7853 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7854  ...
7855 STATUS = NF_PUT_ATT_DOUBLE (NCID, RHID, 'valid_range', NF_DOUBLE, &
7856  2, RHRNGE)
7857 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7858 STATUS = NF_PUT_ATT_TEXT (NCID, NF_GLOBAL, 'title', 19,
7859  'example netCDF dataset')
7860 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7861  ...
7862 STATUS = NF_ENDDEF (NCID) ! leave define mode
7863 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7864 
7865 
7866 7.3 NF\_INQ\_ATT Family
7867 -----------------------
7868 
7869 This family of functions returns information about a netCDF attribute.
7870 All but one of these functions require the variable ID and attribute
7871 name; the exception is NF\_INQ\_ATTNAME. Information about an attribute
7872 includes its type, length, name, and number. See the NF\_GET\_ATT family
7873 for getting attribute values.
7874 
7875 The function NF\_INQ\_ATTNAME gets the name of an attribute, given its
7876 variable ID and number. This function is useful in generic applications
7877 that need to get the names of all the attributes associated with a
7878 variable, since attributes are accessed by name rather than number in
7879 all other attribute functions. The number of an attribute is more
7880 volatile than the name, since it can change when other attributes of the
7881 same variable are deleted. This is why an attribute number is not called
7882 an attribute ID.
7883 
7884 The function NF\_INQ\_ATT returns the attribute’s type and length. The
7885 other functions each return just one item of information about an
7886 attribute.
7887 
7888 Usage
7889 -----
7890 
7891  
7892 
7893 
7894 INTEGER FUNCTION NF_INQ_ATT (INTEGER NCID, INTEGER VARID,
7895  CHARACTER*(*) NAME, INTEGER xtype,
7896  INTEGER len)
7897 INTEGER FUNCTION NF_INQ_ATTTYPE(INTEGER NCID, INTEGER VARID,
7898  CHARACTER*(*) NAME, INTEGER xtype)
7899 INTEGER FUNCTION NF_INQ_ATTLEN (INTEGER NCID, INTEGER VARID,
7900  CHARACTER*(*) NAME, INTEGER len)
7901 INTEGER FUNCTION NF_INQ_ATTNAME(INTEGER NCID, INTEGER VARID,
7902  INTEGER ATTNUM, CHARACTER*(*) name)
7903 INTEGER FUNCTION NF_INQ_ATTID (INTEGER NCID, INTEGER VARID,
7904  CHARACTER*(*) NAME, INTEGER attnum)
7905 
7906 
7907  `NCID`
7908 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
7909 
7910  `VARID`
7911 : Variable ID of the attribute’s variable, or NF\_GLOBAL for a global
7912  attribute.
7913 
7914  `NAME`
7915 : Attribute name. For NF\_INQ\_ATTNAME, this is a pointer to the
7916  location for the returned attribute name.
7917 
7918  `xtype`
7919 : Returned attribute type, one of the set of predefined netCDF
7920  external data types. The valid netCDF external data types are
7921  NF\_BYTE, NF\_CHAR, NF\_SHORT, NF\_INT, NF\_FLOAT, and NF\_DOUBLE.
7922 
7923  `len`
7924 : Returned number of values currently stored in the attribute. For a
7925  string-valued attribute, this is the number of characters in the
7926  string.
7927 
7928  `attnum`
7929 : For NF\_INQ\_ATTNAME, the input attribute number; for
7930  NF\_INQ\_ATTID, the returned attribute number. The attributes for
7931  each variable are numbered from 1 (the first attribute) to NATTS,
7932  where NATTS is the number of attributes for the variable, as
7933  returned from a call to NF\_INQ\_VARNATTS.
7934 
7935  (If you already know an attribute name, knowing its number is not
7936  very useful, because accessing information about an attribute
7937  requires its name.)
7938 
7939 Errors
7940 ------
7941 
7942 Each function returns the value NF\_NOERR if no errors occurred.
7943 Otherwise, the returned status indicates an error. Possible causes of
7944 errors include:
7945 
7946 - The variable ID is invalid for the specified netCDF dataset.
7947 - The specified attribute does not exist.
7948 - The specified netCDF ID does not refer to an open netCDF dataset.
7949 - For NF\_INQ\_ATTNAME, the specified attribute number is negative or
7950  more than the number of attributes defined for the specified
7951  variable.
7952 
7953 Example
7954 -------
7955 
7956 Here is an example using NF\_INQ\_ATT to find out the type and length of
7957 a variable attribute named valid\_range for a netCDF variable named rh
7958 and a global attribute named title in an existing netCDF dataset named
7959 foo.nc:
7960 
7961  
7962 
7963 
7964 INCLUDE 'netcdf.inc'
7965  ...
7966 INTEGER STATUS, NCID
7967 INTEGER RHID ! variable ID
7968 INTEGER VRLEN, TLEN ! attribute lengths
7969  ...
7970 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID)
7971 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7972  ...
7973 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
7974 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7975  ...
7976 STATUS = NF_INQ_ATTLEN (NCID, RHID, 'valid_range', VRLEN)
7977 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7978 STATUS = NF_INQ_ATTLEN (NCID, NF_GLOBAL, 'title', TLEN)
7979 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
7980 
7981 
7982 7.4 NF\_GET\_ATT\_ type
7983 -----------------------
7984 
7985 Members of the NF\_GET\_ATT\_ type family of functions get the value(s)
7986 of a netCDF attribute, given its variable ID and name.
7987 
7988 Usage
7989 -----
7990 
7991  
7992 
7993 
7994 INTEGER FUNCTION NF_GET_ATT_TEXT (INTEGER NCID, INTEGER VARID,
7995  CHARACTER*(*) NAME,
7996  CHARACTER*(*) text)
7997 INTEGER FUNCTION NF_GET_ATT_INT1 (INTEGER NCID, INTEGER VARID,
7998  CHARACTER*(*) NAME,
7999  INTEGER*1 i1vals(*))
8000 INTEGER FUNCTION NF_GET_ATT_INT2 (INTEGER NCID, INTEGER VARID,
8001  CHARACTER*(*) NAME,
8002  INTEGER*2 i2vals(*))
8003 INTEGER FUNCTION NF_GET_ATT_INT (INTEGER NCID, INTEGER VARID,
8004  CHARACTER*(*) NAME,
8005  INTEGER ivals(*))
8006 INTEGER FUNCTION NF_GET_ATT_REAL (INTEGER NCID, INTEGER VARID,
8007  CHARACTER*(*) NAME,
8008  REAL rvals(*))
8009 INTEGER FUNCTION NF_GET_ATT_DOUBLE (INTEGER NCID, INTEGER VARID,
8010  CHARACTER*(*) NAME,
8011  DOUBLE dvals(*))
8012 INTEGER FUNCTION NF_GET_ATT (INTEGER NCID, INTEGER VARID,
8013  CHARACTER*(*) NAME, * vals(*))
8014 
8015 
8016  `NCID`
8017 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
8018 
8019  `VARID`
8020 : Variable ID of the attribute’s variable, or NF\_GLOBAL for a global
8021  attribute.
8022 
8023  `NAME`
8024 : Attribute name.
8025 
8026  `TEXT`\
8027  `I1VALS`\
8028  `I2VALS`\
8029  `IVALS`\
8030  `RVALS`\
8031  `DVALS`\
8032  `VALS`
8033 : Returned attribute values. All elements of the vector of attribute
8034  values are returned, so you must provide enough space to hold them.
8035  If you don’t know how much space to reserve, call NF\_INQ\_ATTLEN
8036  first to find out the length of the attribute. You cannot read
8037  character data from a numeric variable or numeric data from a text
8038  variable. For numeric data, if the type of data differs from the
8039  netCDF variable type, type conversion will occur. See [(netcdf)Type
8040  Conversion](netcdf.html#Type-Conversion) ‘Type Conversion’
8041  in The The NetCDF Users Guide.
8042 
8043 Errors
8044 ------
8045 
8046 NF\_GET\_ATT\_ type returns the value NF\_NOERR if no errors occurred.
8047 Otherwise, the returned status indicates an error. Possible causes of
8048 errors include:
8049 
8050 - The variable ID is invalid for the specified netCDF dataset.
8051 - The specified attribute does not exist.
8052 - The specified netCDF ID does not refer to an open netCDF dataset.
8053 - One or more of the attribute values are out of the range of values
8054  representable by the desired type.
8055 
8056 Example
8057 -------
8058 
8059 Here is an example using NF\_GET\_ATT\_DOUBLE to determine the values of
8060 a variable attribute named valid\_range for a netCDF variable named rh
8061 and a global attribute named title in an existing netCDF dataset named
8062 foo.nc. In this example, it is amed that we don’t know how many
8063 values will be returned, but that we do know the types of the
8064 attributes. Hence, to allocate enough space to store them, we must first
8065 inquire about the length of the attributes.
8066 
8067  
8068 
8069 
8070 INCLUDE 'netcdf.inc'
8071  ...
8072 PARAMETER (MVRLEN=3) ! max number of "valid_range" values
8073 PARAMETER (MTLEN=80) ! max length of "title" attribute
8074 INTEGER STATUS, NCID
8075 INTEGER RHID ! variable ID
8076 INTEGER VRLEN, TLEN ! attribute lengths
8077 DOUBLE PRECISION VRVAL(MVRLEN) ! vr attribute values
8078 CHARACTER*80 TITLE ! title attribute values
8079  ...
8080 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
8081 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8082  ...
8083 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
8084 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8085  ...
8086 ! find out attribute lengths, to makere we have enough space
8087 STATUS = NF_INQ_ATTLEN (NCID, RHID, 'valid_range', VRLEN)
8088 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8089 STATUS = NF_INQ_ATTLEN (NCID, NF_GLOBAL, 'title', TLEN)
8090 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8091 ! get attribute values, if not too big
8092 IF (VRLEN .GT. MVRLEN) THEN
8093  WRITE (*,*) 'valid_range attribute too big!'
8094  CALL EXIT
8095 ELSE
8096  STATUS = NF_GET_ATT_DOUBLE (NCID, RHID, 'valid_range', VRVAL)
8097  IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8098 ENDIF
8099 IF (TLEN .GT. MTLEN) THEN
8100  WRITE (*,*) 'title attribute too big!'
8101  CALL EXIT
8102 ELSE
8103  STATUS = NF_GET_ATT_TEXT (NCID, NF_GLOBAL, 'title', TITLE)
8104  IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8105 ENDIF
8106 
8107 
8108 7.5 NF\_COPY\_ATT
8109 -----------------
8110 
8111 The function NF\_COPY\_ATT copies an attribute from one open netCDF
8112 dataset to another. It can also be used to copy an attribute from one
8113 variable to another within the same netCDF.
8114 
8115 If used to copy an attribute of user-defined type, then that
8116 user-defined type must already be defined in the target file. In the
8117 case of user-defined attributes, enddef/redef is called for ncid\_in and
8118 ncid\_out if they are in define mode. (This is the ere that all
8119 user-defined types are committed to the file(s) before the copy is
8120 attempted.)
8121 
8122 Usage
8123 -----
8124 
8125  
8126 
8127 
8128 INTEGER FUNCTION NF_COPY_ATT (INTEGER NCID_IN, INTEGER VARID_IN,
8129  CHARACTER*(*) NAME, INTEGER NCID_OUT,
8130  INTEGER VARID_OUT)
8131 
8132 
8133  `NCID_IN`
8134 : The netCDF ID of an input netCDF dataset from which the attribute
8135  will be copied, from a previous call to NF\_OPEN or NF\_CREATE.
8136 
8137  `VARID_IN`
8138 : ID of the variable in the input netCDF dataset from which the
8139  attribute will be copied, or NF\_GLOBAL for a global attribute.
8140 
8141  `NAME`
8142 : Name of the attribute in the input netCDF dataset to be copied.
8143 
8144  `NCID_OUT`
8145 : The netCDF ID of the output netCDF dataset to which the attribute
8146  will be copied, from a previous call to NF\_OPEN or NF\_CREATE. It
8147  is permissible for the input and output netCDF IDs to be the same.
8148  The output netCDF dataset should be in define mode if the attribute
8149  to be copied does not already exist for the target variable, or if
8150  it would cause an existing target attribute to grow.
8151 
8152  `VARID_OUT`
8153 : ID of the variable in the output netCDF dataset to which the
8154  attribute will be copied, or NF\_GLOBAL to copy to a global
8155  attribute.
8156 
8157 Errors
8158 ------
8159 
8160 NF\_COPY\_ATT returns the value NF\_NOERR if no errors occurred.
8161 Otherwise, the returned status indicates an error. Possible causes of
8162 errors include:
8163 
8164 - The input or output variable ID is invalid for the specified netCDF
8165  dataset.
8166 - The specified attribute does not exist.
8167 - The output netCDF is not in define mode and the attribute is new for
8168  the output dataset is larger than the existing attribute.
8169 - The input or output netCDF ID does not refer to an open netCDF
8170  dataset.
8171 
8172 Example
8173 -------
8174 
8175 Here is an example using NF\_COPY\_ATT to copy the variable attribute
8176 units from the variable rh in an existing netCDF dataset named foo.nc to
8177 the variable avgrh in another existing netCDF dataset named bar.nc,
8178 aming that the variable avgrh already exists, but does not yet have a
8179 units attribute:
8180 
8181  
8182 
8183 
8184 INCLUDE 'netcdf.inc'
8185  ...
8186 INTEGER STATUS ! error status
8187 INTEGER NCID1, NCID2 ! netCDF IDs
8188 INTEGER RHID, AVRHID ! variable IDs
8189  ...
8190 STATUS = NF_OPEN ('foo.nc', NF_NOWRITE, NCID1)
8191 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8192 STATUS = NF_OPEN ('bar.nc', NF_WRITE, NCID2)
8193 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8194  ...
8195 STATUS = NF_INQ_VARID (NCID1, 'rh', RHID)
8196 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8197 STATUS = NF_INQ_VARID (NCID2, 'avgrh', AVRHID)
8198 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8199  ...
8200 STATUS = NF_REDEF (NCID2) ! enter define mode
8201 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8202 ! copy variable attribute from "rh" to "avgrh"
8203 STATUS = NF_COPY_ATT (NCID1, RHID, 'units', NCID2, AVRHID)
8204 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8205  ...
8206 STATUS = NF_ENDDEF (NCID2) ! leave define mode
8207 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8208 
8209 
8210 7.6 NF\_RENAME\_ATT
8211 -------------------
8212 
8213 The function NF\_RENAME\_ATT changes the name of an attribute. If the
8214 new name is longer than the original name, the netCDF dataset must be in
8215 define mode. You cannot rename an attribute to have the same name as
8216 another attribute of the same variable.
8217 
8218 Usage
8219 -----
8220 
8221  
8222 
8223 
8224 INTEGER FUNCTION NF_RENAME_ATT (INTEGER NCID, INTEGER VARID,
8225  CHARACTER*(*) NAME,
8226  CHARACTER*(*) NEWNAME)
8227 
8228 
8229  `NCID`
8230 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE
8231 
8232  `VARID`
8233 : ID of the attribute’s variable, or NF\_GLOBAL for a global attribute
8234 
8235  `NAME`
8236 : The current attribute name.
8237 
8238  `NEWNAME`
8239 : The new name to be assigned to the specified attribute. If the new
8240  name is longer than the current name, the netCDF dataset must be in
8241  define mode.
8242 
8243 Errors
8244 ------
8245 
8246 NF\_RENAME\_ATT returns the value NF\_NOERR if no errors occurred.
8247 Otherwise, the returned status indicates an error. Possible causes of
8248 errors include:
8249 
8250 - The specified variable ID is not valid.
8251 - The new attribute name is already in use for another attribute of
8252  the specified variable.
8253 - The specified netCDF dataset is in data mode and the new name is
8254  longer than the old name.
8255 - The specified attribute does not exist.
8256 - The specified netCDF ID does not refer to an open netCDF dataset.
8257 
8258 Example
8259 -------
8260 
8261 Here is an example using NF\_RENAME\_ATT to rename the variable
8262 attribute units to Units for a variable rh in an existing netCDF dataset
8263 named foo.nc:
8264 
8265  
8266 
8267 
8268 INCLUDE "netcdf.inc"
8269  ...
8270 INTEGER STATUS ! error status
8271 INTEGER NCID ! netCDF ID
8272 INTEGER RHID ! variable ID
8273  ...
8274 STATUS = NF_OPEN ("foo.nc", NF_NOWRITE, NCID)
8275 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8276  ...
8277 STATUS = NF_INQ_VARID (NCID, "rh", RHID)
8278 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8279  ...
8280 ! rename attribute
8281 STATUS = NF_RENAME_ATT (NCID, RHID, "units", "Units")
8282 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8283 
8284 
8285 7.7 NF\_DEL\_ATT
8286 ----------------
8287 
8288 The function NF\_DEL\_ATT deletes a netCDF attribute from an open netCDF
8289 dataset. The netCDF dataset must be in define mode.
8290 
8291 Usage
8292 -----
8293 
8294 INTEGER FUNCTION NF\_DEL\_ATT (INTEGER NCID, INTEGER VARID,
8295 CHARACTER\*(\*) NAME)
8296 
8297  `NCID`
8298 : NetCDF ID, from a previous call to NF\_OPEN or NF\_CREATE.
8299 
8300  `VARID`
8301 : ID of the attribute’s variable, or NF\_GLOBAL for a global
8302  attribute.
8303 
8304  `NAME`
8305 : The name of the attribute to be deleted.
8306 
8307 Errors
8308 ------
8309 
8310 NF\_DEL\_ATT returns the value NF\_NOERR if no errors occurred.
8311 Otherwise, the returned status indicates an error. Possible causes of
8312 errors include:
8313 
8314 - The specified variable ID is not valid.
8315 - The specified netCDF dataset is in data mode.
8316 - The specified attribute does not exist.
8317 - The specified netCDF ID does not refer to an open netCDF dataset.
8318 
8319 Example
8320 -------
8321 
8322 Here is an example using NF\_DEL\_ATT to delete the variable attribute
8323 Units for a variable rh in an existing netCDF dataset named foo.nc:
8324 
8325  
8326 
8327 
8328 INCLUDE 'netcdf.inc'
8329  ...
8330 INTEGER STATUS ! error status
8331 INTEGER NCID ! netCDF ID
8332 INTEGER RHID ! variable ID
8333  ...
8334 STATUS = NF_OPEN ('foo.nc', NF_WRITE, NCID)
8335 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8336  ...
8337 STATUS = NF_INQ_VARID (NCID, 'rh', RHID)
8338 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8339  ...
8340 ! delete attribute
8341 STATUS = NF_REDEF (NCID) ! enter define mode
8342 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8343 STATUS = NF_DEL_ATT (NCID, RHID, 'Units')
8344 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8345 STATUS = NF_ENDDEF (NCID) ! leave define mode
8346 IF (STATUS .NE. NF_NOERR) CALL HANDLE_ERR(STATUS)
8347 
8348 
8349 A. NetCDF 2 to NetCDF 3 Fortran 77 Transition Guide {.appendix}
8350 ===================================================
8351 
8352 A.1 Overview of FORTRAN interface changes
8353 -----------------------------------------
8354 
8355 NetCDF version 3 includes a complete rewrite of the netCDF library. It
8356 is about twice as fast as the previous version. The netCDF file format
8357 is unchanged, so files written with version 3 can be read with version 2
8358 code and vice versa.
8359 
8360 The core library is now written in ANSI C. You must have an ANSI C
8361 compiler to compile this version. The FORTRAN interface is layered on
8362 top of the C interface using a different technique than was used in
8363 netCDF-2.
8364 
8365 Rewriting the library offered an opportunity to implement improved C and
8366 FORTRAN interfaces that provide some significant benefits:
8367 
8368 - type safety, by eliminating the need to use type punning in
8369  arguments;
8370 - automatic type conversions, by eliminating the undesirable coupling
8371  between the language-independent external netCDF types (NF\_BYTE,
8372  ..., NF\_DOUBLE) and language-dependent internal data types (INT\*1,
8373  ..., DOUBLE PRECISION);
8374 - pport for future enhancements, by eliminating obstacles to the
8375  clean addition ofpport for packed data and multithreading;
8376 - more standard error behavior, by uniformly communicating an error
8377  status back to the calling program in the return value of each
8378  function.
8379 
8380 It is not necessary to rewrite programs that use the version 2 FORTRAN
8381 interface, because the netCDF-3 library includes a backward
8382 compatibility interface thatpports all the old functions, globals,
8383 and behavior. We are hoping that the benefits of the new interface will
8384 be an incentive to use it in new netCDF applications. It is possible to
8385 convert old applications to the new interface incrementally, replacing
8386 netCDF-2 calls with the corresponding netCDF-3 calls one at a time.
8387 
8388 Other changes in the implementation of netCDF rlt in improved
8389 portability, maintainability, and performance on most platforms. A clean
8390 separation between I/O and type layers facilitates platform-specific
8391 optimizations. The new library no longer uses a vendor-provided XDR
8392 library, which simplifies linking programs that use netCDF and speeds up
8393 data access significantly in most cases.
8394 
8395 A.2 The New FORTRAN Interface
8396 -----------------------------
8397 
8398 First, here’s an example of FORTRAN code that uses the netCDF-2
8399 interface:
8400 
8401  
8402 
8403 
8404 ! Use a buffer big enough for values of any type
8405 DOUBLE PRECISION DBUF(NDATA)
8406 REAL RBUF(NDATA)
8407 ...
8408 EQUIVALENCE (RBUF, DBUF), ...
8409 INT XTYPE ! to hold the actual type of the data
8410 INT STATUS ! for error status
8411 ! Get the actual data type
8412 CALL NCVINQ(NCID, VARID, ...,XTYPE, ...)
8413 ...
8414 ! Get the data
8415 CALL NCVGT(NCID, VARID, START, COUNT, DBUF, STATUS)
8416 IF(STATUS .NE. NCNOERR) THEN
8417  PRINT *, 'Cannot get data, error code =', STATUS
8418  ! Deal with error
8419  ...
8420 ENDIF
8421 IF (XTYPE .EQ. NCDOUBLE) THEN
8422  CALL DANALYZE(DBUF)
8423 ELSEIF (XTYPE .EQ. NCFLOAT) THEN
8424  CALL RANALYZE(RBUF)
8425 ...
8426 ENDIF
8427 
8428 
8429 Here’s how you might handle this with the new netCDF-3 FORTRAN
8430 interface:
8431 
8432  
8433 
8434 
8435 ! I want to use doubles for my analysis
8436 DOUBLE PRECISION DBUF(NDATA)
8437 INT STATUS
8438 ! So I use a function that gets the data as doubles.
8439 STATUS = NF_GET_VARA_DOUBLE(NCID, VARID, START, COUNT, DBUF)
8440 IF(STATUS .NE. NF_NOERR) THEN
8441  PRINT *, 'Cannot get data, ', NF_STRERROR(STATUS)
8442  ! Deal with error
8443  ...
8444 ENDIF
8445 CALL DANALYZE(DBUF)
8446 
8447 
8448 The example above illustrates changes in function names, data type
8449 conversion, and error handling, discussed in detail in thes
8450 below.
8451 
8452 A.3 Function Naming Conventions
8453 -------------------------------
8454 
8455 The netCDF-3 Fortran 77 library employs a naming convention intended to
8456 make netCDF programs more readable. For example, the name of the
8457 function to rename a variable is now NF\_RENAME\_VAR instead of the
8458 previous NCVREN.
8459 
8460 All netCDF-3 FORTRAN function names begin with the NF\_ prefix. The
8461 second part of the name is a verb, like GET, PUT, INQ (for inquire), or
8462 OPEN. The third part of the name is typically the object of the verb:
8463 for example DIM, VAR, or ATT for functions dealing with dimensions,
8464 variables, or attributes. To distinguish the various I/O operations for
8465 variables, a single character modifier is appended to VAR:
8466 
8467 - VAR entire variable access
8468 - VAR1 single value access
8469 - VARA array or array access
8470 - VARS strided access to absample of values
8471 - VARM mapped access to values not contiguous in memory
8472 
8473 At the end of the name for variable and attribute functions, there is a
8474 component indicating the type of the final argument: TEXT, INT1, INT2,
8475 INT, REAL, or DOUBLE. This part of the function name indicates the type
8476 of the data container you are using in your program: character string,
8477 1-byte integer, and so on.
8478 
8479 Also, all PARAMETER names in the public FORTRAN interface begin with the
8480 prefix NF\_. For example, the PARAMETER which was formerly MAXNCNAM is
8481 now NF\_MAX\_NAME, and the former FILFLOAT is now NF\_FILL\_FLOAT.
8482 
8483 As previously mentioned, all the old names are stillpported for
8484 backward compatibility.
8485 
8486 A.4 Type Conversion
8487 -------------------
8488 
8489 With the new interface, users need not be aware of the external type of
8490 numeric variables, since automatic conversion to or from any desired
8491 numeric type is now available. You can use this feature to simplify
8492 code, by making it independent of external types. The elimination of
8493 type punning prevents some kinds of type errors that could occur with
8494 the previous interface. Programs may be made more robust with the new
8495 interface, because they need not be changed to accommodate a change to
8496 the external type of a variable.
8497 
8498 If conversion to or from an external numeric type is necessary, it is
8499 handled by the library. This automatic conversion and separation of
8500 external data representation from internal data types will become even
8501 more important in netCDF version 4, when new external types will be
8502 added for packed data for which there is no natural corresponding
8503 internal type, for example, arrays of 11-bit values.
8504 
8505 Converting from one numeric type to another may rlt in an error if
8506 the target type is not capable of representing the converted value. (In
8507 netCDF-2,ch overflows can only happen in the XDR layer.) For example,
8508 a REAL may not be able to hold data stored externally as an NF\_DOUBLE
8509 (an IEEE floating-point number). When accessing an array of values, an
8510 NF\_ERANGE error is returned if one or more values are out of the range
8511 of representable values, but other values are converted properly.
8512 
8513 Note that mere loss of precision in type conversion does not return an
8514 error. Thus, if you read double precision values into an INTEGER, for
8515 example, no error rlts unless the magnitude of the double precision
8516 value exceeds the representable range of INTEGERs on your platform.
8517 Similarly, if you read a large integer into a REAL incapable of
8518 representing all the bits of the integer in its mantissa, this loss
8519 There are two new functions in netCDF-3 that don’t correspond to any
8520 netCDF-2 functions: NF\_INQ\_LIBVERS and NF\_STRERROR. The version ation
8521 The previous implementation returned an error when the same dimension
8522 was used more than once in specifying the shape of a variable in
8523 ncvardef. This restriction is relaxed in the netCDF-3 implementation,
8524 because an autocorrelation matrix is a good example where using the same
8525 dimension twice makes sense.
8526 
8527 In the new interface, units for the IMAP argument to the NF\_PUT\_VARM
8528 and NF\_GET\_VARM families of functions are now in terms of the number
8529 of data elements of the desired internal type, not in terms of bytes as
8530 in the netCDF version-2 mapped access interfaces.
8531 
8532 Following is a table of netCDF-2 function names and names of the
8533 corresponding netCDF-3 functions. For parameter lists of netCDF-2
8534 functions, see the netCDF-2 User’s Guide.
8535 
8536  `NCABOR`
8537 : NF\_ABORT
8538 
8539  `NCACPY`
8540 : NF\_COPY\_ATT
8541 
8542  `NCADEL`
8543 : NF\_DEL\_ATT
8544 
8545  `NCAGT`
8546 : NF\_GET\_ATT\_DOUBLE, NF\_GET\_ATT\_REAL, NF\_GET\_ATT\_INT,
8547  NF\_GET\_ATT\_INT1, NF\_GET\_ATT\_INT2
8548 
8549  `NCAGTC`
8550 : NF\_GET\_ATT\_TEXT
8551 
8552  `NCAINQ`
8553 : NF\_INQ\_ATT, NF\_INQ\_ATTID, NF\_INQ\_ATTLEN, NF\_INQ\_ATTTYPE
8554 
8555  `NCANAM`
8556 : NF\_INQ\_ATTNAME
8557 
8558  `NCAPT`
8559 : NF\_PUT\_ATT\_DOUBLE, NF\_PUT\_ATT\_REAL, NF\_PUT\_ATT\_INT,
8560  NF\_PUT\_ATT\_INT1NF\_PUT
8561 
8562 B. Summary of FORTRAN 77 Interface {.appendix}
8563 ==================================
8564 
8565 Input parameters are in upper case, output parameters are in lower case.
8566 The FORTRAN types of all the parameters are listed alphabetically by
8567 parameter name below the function declarations.
8568 
8569  
8570 
8571 
8572 CHARACTER*80 FUNCTION NF_INQ_LIBVERS()
8573 CHARACTER*80 FUNCTION NF_STRERROR (NCERR)
8574 INTEGER FUNCTION NF_CREATE (PATH, CMODE, ncid)
8575 INTEGER FUNCTION NF_OPEN (PATH, MODE, ncid)
8576 INTEGER FUNCTION NF_SET_FILL (NCID, FILLMODE, old_mode)
8577 INTEGER FUNCTION NF_REDEF (NCID)
8578 INTEGER FUNCTION NF_ENDDEF (NCID)
8579 INTEGER FUNCTION NF_SYNC (NCID)
8580 INTEGER FUNCTION NF_ABORT (NCID)
8581 INTEGER FUNCTION NF_CLOSE (NCID)
8582 INTEGER FUNCTION NF_INQ (NCID, ndims, nvars, ngatts,
8583  unlimdimid)
8584 INTEGER FUNCTION NF_INQ_NDIMS (NCID, ndims)
8585 INTEGER FUNCTION NF_INQ_NVARS (NCID, nvars)
8586 INTEGER FUNCTION NF_INQ_NATTS (NCID, ngatts)
8587 INTEGER FUNCTION NF_INQ_UNLIMDIM (NCID, unlimdimid)
8588 INTEGER FUNCTION NF_DEF_DIM (NCID, NAME, LEN, dimid)
8589 INTEGER FUNCTION NF_INQ_DIMID (NCID, NAME, dimid)
8590 INTEGER FUNCTION NF_INQ_DIM (NCID, DIMID, name, len)
8591 INTEGER FUNCTION NF_INQ_DIMNAME (NCID, DIMID, name)
8592 INTEGER FUNCTION NF_INQ_DIMLEN (NCID, DIMID, len)
8593 INTEGER FUNCTION NF_RENAME_DIM (NCID, DIMID, NAME)
8594 
8595 INTEGER FUNCTION NF_DEF_VAR (NCID, NAME, XTYPE, NDIMS, DIMIDS,
8596  varid)
8597 INTEGER FUNCTION NF_INQ_VAR (NCID, VARID, name, xtype, ndims,
8598  dimids, natts)
8599 INTEGER FUNCTION NF_INQ_VARID (NCID, NAME, varid)
8600 INTEGER FUNCTION NF_INQ_VARNAME (NCID, VARID, name)
8601 INTEGER FUNCTION NF_INQ_VARTYPE (NCID, VARID, xtype)
8602 INTEGER FUNCTION NF_INQ_VARNDIMS (NCID, VARID, ndims)
8603 INTEGER FUNCTION NF_INQ_VARDIMID (NCID, VARID, DIMIDS)
8604 INTEGER FUNCTION NF_INQ_VARNATTS (NCID, VARID, natts)
8605 INTEGER FUNCTION NF_RENAME_VAR (NCID, VARID, NAME)
8606 INTEGER FUNCTION NF_PUT_VAR_TEXT (NCID, VARID, TEXT)
8607 INTEGER FUNCTION NF_GET_VAR_TEXT (NCID, VARID, text)
8608 INTEGER FUNCTION NF_PUT_VAR_INT1 (NCID, VARID, I1VAL)
8609 INTEGER FUNCTION NF_GET_VAR_INT1 (NCID, VARID, i1val)
8610 INTEGER FUNCTION NF_PUT_VAR_INT2 (NCID, VARID, I2VAL)
8611 INTEGER FUNCTION NF_GET_VAR_INT2 (NCID, VARID, i2val)
8612 INTEGER FUNCTION NF_PUT_VAR_INT (NCID, VARID, IVAL)
8613 INTEGER FUNCTION NF_GET_VAR_INT (NCID, VARID, ival)
8614 INTEGER FUNCTION NF_PUT_VAR_REAL (NCID, VARID, RVAL)
8615 INTEGER FUNCTION NF_GET_VAR_REAL (NCID, VARID, rval)
8616 INTEGER FUNCTION NF_PUT_VAR_DOUBLE (NCID, VARID, DVAL)
8617 INTEGER FUNCTION NF_GET_VAR_DOUBLE (NCID, VARID, dval)
8618 INTEGER FUNCTION NF_PUT_VAR1_TEXT (NCID, VARID, INDEX, TEXT)
8619 INTEGER FUNCTION NF_GET_VAR1_TEXT (NCID, VARID, INDEX, text)
8620 INTEGER FUNCTION NF_PUT_VAR1_INT1 (NCID, VARID, INDEX, I1VAL)
8621 INTEGER FUNCTION NF_GET_VAR1_INT1 (NCID, VARID, INDEX, i1val)
8622 INTEGER FUNCTION NF_PUT_VAR1_INT2 (NCID, VARID, INDEX, I2VAL)
8623 INTEGER FUNCTION NF_GET_VAR1_INT2 (NCID, VARID, INDEX, i2val)
8624 INTEGER FUNCTION NF_PUT_VAR1_INT (NCID, VARID, INDEX, IVAL)
8625 INTEGER FUNCTION NF_GET_VAR1_INT (NCID, VARID, INDEX, ival)
8626 INTEGER FUNCTION NF_PUT_VAR1_REAL (NCID, VARID, INDEX, RVAL)
8627 INTEGER FUNCTION NF_GET_VAR1_REAL (NCID, VARID, INDEX, rval)
8628 INTEGER FUNCTION NF_PUT_VAR1_DOUBLE(NCID, VARID, INDEX, DVAL)
8629 INTEGER FUNCTION NF_GET_VAR1_DOUBLE(NCID, VARID, INDEX, dval)
8630 INTEGER FUNCTION NF_PUT_VARA_TEXT (NCID, VARID, START, COUNT, TEXT)
8631 INTEGER FUNCTION NF_GET_VARA_TEXT (NCID, VARID, START, COUNT, text)
8632 INTEGER FUNCTION NF_PUT_VARA_INT1 (NCID, VARID, START, COUNT, I1VALS)
8633 INTEGER FUNCTION NF_GET_VARA_INT1 (NCID, VARID, START, COUNT, i1vals)
8634 INTEGER FUNCTION NF_PUT_VARA_INT2 (NCID, VARID, START, COUNT, I2VALS)
8635 INTEGER FUNCTION NF_GET_VARA_INT2 (NCID, VARID, START, COUNT, i2vals)
8636 INTEGER FUNCTION NF_PUT_VARA_INT (NCID, VARID, START, COUNT, IVALS)
8637 INTEGER FUNCTION NF_GET_VARA_INT (NCID, VARID, START, COUNT, ivals)
8638 INTEGER FUNCTION NF_PUT_VARA_REAL (NCID, VARID, START, COUNT, RVALS)
8639 INTEGER FUNCTION NF_GET_VARA_REAL (NCID, VARID, START, COUNT, rvals)
8640 INTEGER FUNCTION NF_PUT_VARA_DOUBLE(NCID, VARID, START, COUNT, DVALS)
8641 INTEGER FUNCTION NF_GET_VARA_DOUBLE(NCID, VARID, START, COUNT, dvals)
8642 INTEGER FUNCTION NF_PUT_VARS_TEXT (NCID, VARID, START, COUNT, STRIDE,
8643  TEXT)
8644 INTEGER FUNCTION NF_GET_VARS_TEXT (NCID, VARID, START, COUNT, STRIDE,
8645  text)
8646 INTEGER FUNCTION NF_PUT_VARS_INT1 (NCID, VARID, START, COUNT, STRIDE,
8647  I1VALS)
8648 INTEGER FUNCTION NF_GET_VARS_INT1 (NCID, VARID, START, COUNT, STRIDE,
8649  i1vals)
8650 INTEGER FUNCTION NF_PUT_VARS_INT2 (NCID, VARID, START, COUNT, STRIDE,
8651  I2VALS)
8652 INTEGER FUNCTION NF_GET_VARS_INT2 (NCID, VARID, START, COUNT, STRIDE,
8653  i2vals)
8654 INTEGER FUNCTION NF_PUT_VARS_INT (NCID, VARID, START, COUNT, STRIDE,
8655  IVALS)
8656 INTEGER FUNCTION NF_GET_VARS_INT (NCID, VARID, START, COUNT, STRIDE,
8657  ivals)
8658 INTEGER FUNCTION NF_PUT_VARS_REAL (NCID, VARID, START, COUNT, STRIDE,
8659  RVALS)
8660 INTEGER FUNCTION NF_GET_VARS_REAL (NCID, VARID, START, COUNT, STRIDE,
8661  rvals)
8662 INTEGER FUNCTION NF_PUT_VARS_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
8663  DVALS)
8664 INTEGER FUNCTION NF_GET_VARS_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
8665  dvals)
8666 INTEGER FUNCTION NF_PUT_VARM_TEXT (NCID, VARID, START, COUNT, STRIDE,
8667  IMAP, TEXT)
8668 INTEGER FUNCTION NF_GET_VARM_TEXT (NCID, VARID, START, COUNT, STRIDE,
8669  IMAP, text)
8670 INTEGER FUNCTION NF_PUT_VARM_INT1 (NCID, VARID, START, COUNT, STRIDE,
8671  IMAP, I1VALS)
8672 INTEGER FUNCTION NF_GET_VARM_INT1 (NCID, VARID, START, COUNT, STRIDE,
8673  IMAP, i1vals)
8674 INTEGER FUNCTION NF_PUT_VARM_INT2 (NCID, VARID, START, COUNT, STRIDE,
8675  IMAP, I2VALS)
8676 INTEGER FUNCTION NF_GET_VARM_INT2 (NCID, VARID, START, COUNT, STRIDE,
8677  IMAP, i2vals)
8678 INTEGER FUNCTION NF_PUT_VARM_INT (NCID, VARID, START, COUNT, STRIDE,
8679  IMAP, IVALS)
8680 INTEGER FUNCTION NF_GET_VARM_INT (NCID, VARID, START, COUNT, STRIDE,
8681  IMAP, ivals)
8682 INTEGER FUNCTION NF_PUT_VARM_REAL (NCID, VARID, START, COUNT, STRIDE,
8683  IMAP, RVALS)
8684 INTEGER FUNCTION NF_GET_VARM_REAL (NCID, VARID, START, COUNT, STRIDE,
8685  IMAP, rvals)
8686 INTEGER FUNCTION NF_PUT_VARM_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
8687  IMAP, DVALS)
8688 INTEGER FUNCTION NF_GET_VARM_DOUBLE(NCID, VARID, START, COUNT, STRIDE,
8689  IMAP, dvals)
8690 
8691 INTEGER FUNCTION NF_INQ_ATT (NCID, VARID, NAME, xtype, len)
8692 INTEGER FUNCTION NF_INQ_ATTID (NCID, VARID, NAME, attnum)
8693 INTEGER FUNCTION NF_INQ_ATTTYPE (NCID, VARID, NAME, xtype)
8694 INTEGER FUNCTION NF_INQ_ATTLEN (NCID, VARID, NAME, len)
8695 INTEGER FUNCTION NF_INQ_ATTNAME (NCID, VARID, ATTNUM, name)
8696 INTEGER FUNCTION NF_COPY_ATT (NCID_IN, VARID_IN, NAME,
8697  NCID_OUT, VARID_OUT)
8698 INTEGER FUNCTION NF_RENAME_ATT (NCID, VARID, CURNAME, NEWNAME)
8699 INTEGER FUNCTION NF_DEL_ATT (NCID, VARID, NAME)
8700 INTEGER FUNCTION NF_PUT_ATT_TEXT (NCID, VARID, NAME, LEN, TEXT)
8701 INTEGER FUNCTION NF_GET_ATT_TEXT (NCID, VARID, NAME, text)
8702 INTEGER FUNCTION NF_PUT_ATT_INT1 (NCID, VARID, NAME, XTYPE, LEN,
8703  I1VALS)
8704 INTEGER FUNCTION NF_GET_ATT_INT1 (NCID, VARID, NAME, i1vals)
8705 INTEGER FUNCTION NF_PUT_ATT_INT2 (NCID, VARID, NAME, XTYPE, LEN,
8706  I2VALS)
8707 INTEGER FUNCTION NF_GET_ATT_INT2 (NCID, VARID, NAME, i2vals)
8708 INTEGER FUNCTION NF_PUT_ATT_INT (NCID, VARID, NAME, XTYPE, LEN,
8709  IVALS)
8710 INTEGER FUNCTION NF_GET_ATT_INT (NCID, VARID, NAME, ivals)
8711 INTEGER FUNCTION NF_PUT_ATT_REAL (NCID, VARID, NAME, XTYPE, LEN,
8712  RVALS)
8713 INTEGER FUNCTION NF_GET_ATT_REAL (NCID, VARID, NAME, rvals)
8714 INTEGER FUNCTION NF_PUT_ATT_DOUBLE (NCID, VARID, NAME, XTYPE, LEN,
8715  DVALS)
8716 INTEGER FUNCTION NF_GET_ATT_DOUBLE (NCID, VARID, NAME, dvals)
8717 
8718 INTEGER ATTNUM ! attribute number
8719 INTEGER attnum ! returned attribute number
8720 INTEGER CMODE ! NF_NOCLOBBER, NF_SHARE flags expression
8721 INTEGER COUNT ! array of edge lengths of block of values
8722 CHARACTER(*) CURNAME ! current name (before renaming)
8723 INTEGER DIMID ! dimension ID
8724 INTEGER dimid ! returned dimension ID
8725 INTEGER DIMIDS ! list of dimension IDs
8726 INTEGER dimids ! list of returned dimension IDs
8727 DOUBLEPRECISION DVAL ! single data value
8728 DOUBLEPRECISION dval ! returned single data value
8729 DOUBLEPRECISION DVALS ! array of data values
8730 DOUBLEPRECISION dvals ! array of returned data values
8731 INTEGER FILLMODE ! NF_NOFILL or NF_FILL, for setting fill mode
8732 INTEGER*1 I1VAL ! single data value
8733 INTEGER*1 I1val ! returned single data value
8734 INTEGER*1 I1VALS ! array of data values
8735 INTEGER*1 i1vals ! array of returned data values
8736 INTEGER*2 I2VAL ! single data value
8737 INTEGER*2 i2val ! returned single data value
8738 INTEGER*2 I2VALS ! array of data values
8739 INTEGER*2 i2vals ! array of returned data values
8740 INTEGER IMAP ! index mapping vector
8741 INTEGER INDEX ! variable array index vector
8742 INTEGER IVAL ! single data value
8743 INTEGER ival ! returned single data value
8744 INTEGER IVALS ! array of data values
8745 INTEGER ivals ! array of returned data values
8746 INTEGER LEN ! dimension or attribute length
8747 INTEGER len ! returned dimension or attribute length
8748 INTEGER MODE ! open mode, one of NF_WRITE or NF_NOWRITE
8749 CHARACTER(*) NAME ! dimension, variable, or attribute name
8750 CHARACTER(*) name ! returned dim, var, or att name
8751 INTEGER natts ! returned number of attributes
8752 INTEGER NCERR ! error returned from NF_xxx function call
8753 INTEGER NCID ! netCDF ID of an open netCDF dataset
8754 INTEGER ncid ! returned netCDF ID
8755 INTEGER NCID_IN ! netCDF ID of open source netCDF dataset
8756 INTEGER NCID_OUT ! netCDF ID of open destination netCDF dataset
8757 INTEGER NDIMS ! number of dimensions
8758 INTEGER ndims ! returned number of dimensions
8759 CHARACTER(*) NEWNAME ! new name for dim, var, or att
8760 INTEGER ngatts ! returned number of global attributes
8761 INTEGER nvars ! returned number of variables
8762 INTEGER old_mode ! previous fill mode, NF_NOFILL or NF_FILL,
8763 CHARACTER(*) PATH ! name of netCDF dataset
8764 REAL RVAL ! single data value
8765 REAL rval ! returned single data value
8766 REAL RVALS ! array of data values
8767 REAL rvals ! array of returned data values
8768 INTEGER START ! variable array indices of first value
8769 INTEGER STRIDE ! variable array dimensional strides
8770 CHARACTER(*) TEXT ! input text value
8771 CHARACTER(*) text ! returned text value
8772 INTEGER unlimdimid ! returned ID of unlimited dimension
8773 INTEGER VARID ! variable ID
8774 INTEGER varid ! returned variable ID
8775 INTEGER VARID_IN ! variable ID
8776 INTEGER VARID_OUT ! variable ID
8777 INTEGER XTYPE ! external type: NF_BYTE, NF_CHAR, ... ,
8778 INTEGER xtype ! returned external type
8779 

Return to the Main Unidata NetCDF page.
Generated on Sun Dec 27 2015 13:19:48 for NetCDF-Fortran. NetCDF is a Unidata library.