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

Return to the Main Unidata NetCDF page.
Generated on Sun Mar 27 2016 13:46:12 for NetCDF-Fortran. NetCDF is a Unidata library.