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

Return to the Main Unidata NetCDF page.
Generated on Thu Nov 9 2017 06:56:52 for NetCDF-Fortran. NetCDF is a Unidata library.