1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
|
<!-- Generated by Harlequin WebMaker 2.2.3 (24-Apr-1996)
LispWorks 3.2.2 -->
<HTML> <HEAD>
<TITLE>7 Variables</TITLE>
</HEAD>
<BODY bgcolor="#ffffff">
<A NAME=HEADING12></A>
<A HREF="guidec-13.html">[Next] </A><A HREF="guidec-11.html">[Previous] </A><A HREF="guidec-1.html">[Top] </A><A HREF="guidec-3.html">[Contents] </A><A HREF="guidec-21.html">[Index] </A><A HREF="http://www.unidata.ucar.edu/packages/netcdf/">[netCDF Home Page]</A><A HREF="http://www.unidata.ucar.edu/">[Unidata Home Page]</A><P>
NetCDF User's Guide for C<P>
<A NAME=HEADING12-0></A>
<H1>7 <A NAME=MARKER-10-2449></A>Variables</H1>
<HR>
Variables <A NAME=MARKER-2-2450></A><A NAME=MARKER-2-2451></A><A NAME=MARKER-2-2452></A><A NAME=MARKER-2-2453></A><A NAME=MARKER-2-2454></A><A NAME=MARKER-2-2455></A><A NAME=MARKER-2-2456></A><A NAME=MARKER-2-2457></A><A NAME=MARKER-2-2458></A>for a netCDF dataset are defined when the dataset is created, while the netCDF dataset is in define mode. Other variables may be added later by reentering define mode. A netCDF variable has a name, a type, and a shape, which are specified when it is defined. A variable may also have values, which are established later in data mode. <P>
Ordinarily, <A NAME=MARKER-2-2459></A><A NAME=MARKER-2-2460></A><A NAME=MARKER-2-2461></A><A NAME=MARKER-2-2462></A><A NAME=MARKER-2-2463></A><A NAME=MARKER-2-2464></A>the name, type, and shape are fixed when the variable is first defined. The name may be changed, but the type and shape of a variable cannot be changed. However, a variable defined in terms of the unlimited dimension can grow without bound in that dimension. <P>
A <A NAME=MARKER-2-2465></A><A NAME=MARKER-2-2466></A>netCDF variable in an open netCDF dataset is referred to by a small integer called a <I>variable ID</I>.<P>
Variable IDs reflect the order in which variables were defined within a netCDF dataset. Variable IDs are 0,<A NAME=MARKER-10-2467></A> 1,<A NAME=MARKER-10-2468></A> 2,<A NAME=MARKER-10-2469></A>..., in the order in which the variables were defined. A function is available for getting the variable ID from the variable name and vice-versa. <P>
Attributes (<A HREF=guidec-13.html#MARKER-9-2826>see Chapter 8 "Attributes," page 81</A>) may be associated with a variable to specify such properties as units.<P>
Operations supported on variables are:<P>
<UL>
<LI>Create a variable, given its name, data type, and shape.<P>
<LI>Get a variable ID from its name.<P>
<LI>Get a variable's name, data type, shape, and number of attributes from its ID.<P>
<LI>Put a data value into a variable, given variable ID, indices, and value.<P>
<LI>Put an array of values into a variable, given variable ID, corner indices, edge lengths, and a block of values.<P>
<LI>Put a subsampled or mapped array-section of values into a variable, given variable ID, corner indices, edge lengths, stride vector, index mapping vector, and a block of values.<P>
<LI>Get a data value from a variable, given variable ID and indices.<P>
<LI>Get an array of values from a variable, given variable ID, corner indices, and edge lengths.<P>
<LI>Get a subsampled or mapped array-section of values from a variable, given variable ID, corner indices, edge lengths, stride vector, and index mapping vector.<P>
<LI>Rename a variable.<P>
</UL>
<A NAME=HEADING12-17></A>
<H2>7.1 Language Types Corresponding to netCDF external data types</H2>
<HR>
The <A NAME=MARKER-2-2480></A><A NAME=MARKER-2-2481></A><A NAME=MARKER-2-2482></A><A NAME=MARKER-2-2483></A><A NAME=MARKER-2-2484></A><A NAME=MARKER-2-2485></A><A NAME=MARKER-2-2486></A><A NAME=MARKER-2-2487></A>following table gives the netCDF external data types and the corresponding type constants for defining variables in the C <A NAME=MARKER-10-2488></A>interface:<P>
<TABLE BORDER="1"><TH><B>netCDF/CDL Data Type</B><TH><B>C API Mnemonic</B><TH><B>Bits</B><TR>
<TD><CODE>byte</CODE><TD><CODE><A NAME=MARKER-2-108></A>NC_BYTE <A NAME=MARKER-10-109></A></CODE><TD>8<TR>
<TD><CODE>char</CODE><TD><CODE><A NAME=MARKER-2-110></A>NC_CHAR <A NAME=MARKER-10-111></A></CODE><TD>8<TR>
<TD><CODE>short</CODE><TD><CODE><A NAME=MARKER-2-112></A>NC_SHORT <A NAME=MARKER-10-113></A></CODE><TD>16<TR>
<TD><CODE>int</CODE><TD><CODE><A NAME=MARKER-2-114></A>NC_INT <A NAME=MARKER-10-115></A></CODE><TD>32<TR>
<TD><CODE>float</CODE><TD><CODE><A NAME=MARKER-2-116></A>NC_FLOAT <A NAME=MARKER-10-117></A></CODE><TD>32<TR>
<TD><CODE>double</CODE><TD><CODE><A NAME=MARKER-2-118></A>NC_DOUBLE <A NAME=MARKER-10-119></A></CODE><TD>64</TABLE>
<P>
The first column gives the netCDF external data type, which is the same as the CDL data type. The next column gives the corresponding C preprocessor macro <A NAME=MARKER-10-2489></A>for use in netCDF functions (the preprocessor macros are defined in the netCDF C header-file <CODE>netcdf.h</CODE>)<A NAME=MARKER-10-2490></A>. The last column gives the number of bits used in the external representation of values of the corresponding type.<P>
Note that there are no netCDF types corresponding to 64-bit integers or to characters wider than 8 bits in the current version of the netCDF library. <P>
<A NAME=HEADING12-22></A>
<H2>7.2 Create a Variable: <CODE><A NAME=MARKER-2-2491></A>nc_def_var</CODE> <A NAME=MARKER-10-2492></A><CODE></CODE></H2>
<HR>
The <A NAME=MARKER-2-2493></A><A NAME=MARKER-2-2494></A><A NAME=MARKER-2-2495></A>function <CODE>nc_def_var</CODE> <A NAME=MARKER-10-2496></A>adds a new variable to an open netCDF dataset in define mode. It returns (as an argument) a variable ID, given the netCDF ID, the variable name, the variable type, the number of dimensions, and a list of the dimension IDs. <P>
<A NAME=HEADING12-24></A>
<H4>Usage </H4>
<PRE>
int nc_def_var (int ncid, const char *name, nc_type xtype,
int ndims, const int dimids[], int *varidp);
<TABLE BORDER="1"><TD><CODE>ncid</CODE><TD>NetCDF ID, from a previous call to <CODE>nc_open</CODE> or <CODE>nc_create</CODE>.<TR>
<TD><CODE>name</CODE><TD>Variable name. Must begin with an alphabetic character, followed by zero or more alphanumeric characters including the underscore ('<CODE>_</CODE>'). Case is significant.<TR>
<TD><CODE>xtype</CODE><TD>One of the set of predefined netCDF external data types. The type of this parameter, <CODE><A NAME=MARKER-2-158></A>nc_type</CODE>, is defined in the netCDF header file. The valid netCDF external data types are <CODE>NC_BYTE</CODE>, <CODE>NC_CHAR</CODE>, <CODE>NC_SHORT</CODE>, <CODE>NC_INT</CODE>, <CODE>NC_FLOAT</CODE>, and <CODE>NC_DOUBLE</CODE>.<TR>
<TD><CODE>ndims</CODE><TD>Number of dimensions for the variable. For example, <CODE>2</CODE> specifies a matrix, <CODE>1</CODE> specifies a vector, and <CODE>0</CODE> means the variable is a scalar with no dimensions. Must not be negative or greater than the predefined constant <CODE>NC_MAX_VAR_DIMS</CODE>.<TR>
<TD><CODE>dimids</CODE><TD>Vector of <CODE>ndims</CODE> dimension IDs corresponding to the variable dimensions. If the ID of the unlimited dimension is included, it must be first. This argument is ignored if <CODE>ndims</CODE> is <CODE>0</CODE>.<TR>
<TD><CODE>varidp</CODE><TD>Pointer to location for the returned variable ID.</TABLE>
</PRE>
Errors <A NAME=MARKER-10-2497></A><P>
<CODE>nc_def_var</CODE> <A NAME=MARKER-10-2498></A>returns the value <CODE>NC_NOERR</CODE> <A NAME=MARKER-10-2499></A>if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include: <P>
<UL>
<LI>The netCDF dataset is not in define mode.<P>
<LI>The specified variable name is the name of another existing variable.<P>
<LI>The specified type is not a valid netCDF type.<P>
<LI>The <A NAME=MARKER-2-2502></A><A NAME=MARKER-2-2503></A><A NAME=MARKER-2-2504></A><A NAME=MARKER-2-2505></A><A NAME=MARKER-2-2506></A><A NAME=MARKER-2-2507></A><A NAME=MARKER-2-2508></A>specified number of dimensions is negative or more than the constant <CODE>NC_MAX_VAR_DIMS</CODE>,<A NAME=MARKER-10-2509></A> the maximum number of dimensions permitted for a netCDF variable. <P>
<LI>One <A NAME=MARKER-2-2510></A><A NAME=MARKER-2-2511></A>or more of the dimension IDs in the list of dimensions is not a valid dimension ID for the netCDF dataset.<P>
<LI>The <A NAME=MARKER-2-2512></A><A NAME=MARKER-2-2513></A>number of variables would exceed the constant <CODE><A NAME=MARKER-2-2514></A>NC_MAX_VARS</CODE>,<A NAME=MARKER-10-2515></A> the maximum number of variables permitted in a netCDF dataset. <P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-36></A>
<H4>Example </H4>
Here <A NAME=MARKER-2-2516></A>is an example using <CODE>nc_def_var</CODE> <A NAME=MARKER-10-2517></A>to create a variable named <CODE>rh</CODE> of type <CODE>double</CODE> with three dimensions, <CODE>time</CODE>, <CODE>lat</CODE>, and <CODE>lon</CODE> in a new netCDF dataset named <CODE>foo.nc</CODE>:<P>
<PRE>
#include <netcdf.h>
...
int status; /* error status */
int ncid; /* netCDF ID */
int lat_dim, lon_dim, time_dim; /* dimension IDs */
int rh_id; /* variable ID */
int rh_dimids[3]; /* variable shape */
...
status = nc_create("foo.nc", NC_NOCLOBBER, &ncid);
if (status != NC_NOERR) handle_error(status);
...
/* define dimensions */
status = nc_def_dim(ncid, "lat", 5L, &lat_dim);
if (status != NC_NOERR) handle_error(status);
status = nc_def_dim(ncid, "lon", 10L, &lon_dim);
if (status != NC_NOERR) handle_error(status);
status = nc_def_dim(ncid, "time", NC_UNLIMITED, &time_dim);
if (status != NC_NOERR) handle_error(status);
...
/* define variable */
rh_dimids[0] = time_dim;
rh_dimids[1] = lat_dim;
rh_dimids[2] = lon_dim;
status = nc_def_var (ncid, "rh", NC_DOUBLE, 3, rh_dimids, &rh_id);
if (status != NC_NOERR) handle_error(status);
</PRE>
<A NAME=HEADING12-63></A>
<H2>7.3 <A NAME=MARKER-10-2518></A><A NAME=MARKER-2-2519></A>Get a Variable ID from Its Name: <CODE><A NAME=MARKER-2-2520></A>nc_inq_varid</CODE> <A NAME=MARKER-10-2521></A><CODE></CODE></H2>
<HR>
The function <CODE>nc_inq_varid</CODE> <A NAME=MARKER-10-2522></A>returns the ID of a netCDF variable, given its name.<P>
<A NAME=HEADING12-65></A>
<H4>Usage </H4>
<PRE>
int nc_inq_varid (int ncid, const char *name, int *varidp);
<TABLE BORDER="1"><TD><CODE>ncid</CODE><TD>NetCDF ID, from a previous call to <CODE>nc_open</CODE> or <CODE>nc_create</CODE>.<TR>
<TD><CODE>name</CODE><TD>Variable name for which ID is desired.<TR>
<TD><CODE>varidp</CODE><TD>Pointer to location for returned variable ID.</TABLE>
</PRE>
Errors <A NAME=MARKER-10-2523></A><P>
<CODE>nc_inq_varid</CODE> <A NAME=MARKER-10-2524></A>returns the value <CODE>NC_NOERR <A NAME=MARKER-10-2525></A></CODE>if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The specified variable name is not a valid name for a variable in the specified netCDF dataset.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-71></A>
<H4>Example </H4>
Here <A NAME=MARKER-2-2526></A>is an example using <CODE>nc_inq_varid</CODE> <A NAME=MARKER-10-2527></A>to find out the ID of a variable named <CODE>rh</CODE> in an existing netCDF dataset named <CODE>foo.nc</CODE>:<P>
<PRE>
#include <netcdf.h>
...
int status, ncid, rh_id;
...
status = nc_open("foo.nc", NC_NOWRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid (ncid, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
</PRE>
<A NAME=HEADING12-82></A>
<H2>7.4 <A NAME=MARKER-10-2528></A>Get Information about a Variable from Its ID: <CODE><A NAME=MARKER-2-2529></A>nc_inq_var</CODE> <CODE><A NAME=MARKER-10-2530></A></CODE>family</H2>
<HR>
A <A NAME=MARKER-2-2531></A><A NAME=MARKER-2-2532></A><A NAME=MARKER-2-2533></A><A NAME=MARKER-2-2534></A><A NAME=MARKER-2-2535></A><A NAME=MARKER-2-2536></A><A NAME=MARKER-2-2537></A><A NAME=MARKER-2-2538></A><A NAME=MARKER-2-2539></A><A NAME=MARKER-2-2540></A><A NAME=MARKER-2-2541></A><A NAME=MARKER-2-2542></A><A NAME=MARKER-2-2543></A><A NAME=MARKER-2-2544></A>family of functions that returns information about a netCDF variable, given its ID. Information about a variable includes its name, type, number of dimensions, a list of dimension IDs describing the shape of the variable, and the number of variable attributes that have been assigned to the variable. <P>
The function <CODE>nc_inq_var <A NAME=MARKER-10-2545></A></CODE>returns all the information about a netCDF variable, given its ID. The other functions each return just one item of information about a variable. <P>
These other functions include <CODE><A NAME=MARKER-2-2546></A>nc_inq_varname</CODE>,<A NAME=MARKER-10-2547></A><A NAME=MARKER-2-2548></A> <CODE>nc_inq_vartype</CODE>,<A NAME=MARKER-10-2549></A> <CODE><A NAME=MARKER-2-2550></A>nc_inq_varndims</CODE>,<A NAME=MARKER-2-2551></A><A NAME=MARKER-10-2552></A> <CODE>nc_inq_vardimid</CODE>,<A NAME=MARKER-10-2553></A> and<A NAME=MARKER-2-2554></A> <CODE>nc_inq_varnatts</CODE>.<A NAME=MARKER-10-2555></A> <P>
<A NAME=HEADING12-86></A>
<H4>Usage </H4>
<PRE>
int nc_inq_var (int ncid, int varid, char *name, nc_type *xtypep,
int *ndimsp, int dimids[], int *nattsp);
int nc_inq_varname (int ncid, int varid, char *name);
int nc_inq_vartype (int ncid, int varid, nc_type *xtypep);
int nc_inq_varndims (int ncid, int varid, int *ndimsp);
int nc_inq_vardimid (int ncid, int varid, int dimids[]);
int nc_inq_varnatts (int ncid, int varid, int *nattsp);
<TABLE BORDER="1"><TD><CODE>ncid</CODE><TD>NetCDF ID, from a previous call to <CODE>nc_open</CODE> or <CODE>nc_create</CODE>.<TR>
<TD><CODE>varid</CODE><TD>Variable ID.<TR>
<TD><CODE>name</CODE><TD>Returned <A NAME=MARKER-2-164></A><A NAME=MARKER-2-165></A><A NAME=MARKER-2-166></A>variable name. The caller must allocate space for the returned name. The maximum possible length, in characters, of a variable name is given by the predefined constant <CODE>NC_MAX_NAME</CODE>. <TR>
<TD><CODE>xtypep</CODE><TD>Pointer to location for returned variable type, one of the set of predefined netCDF external data types. The type of this parameter, <CODE>nc_type</CODE>, is defined in the netCDF header file. The valid netCDF external data types are <CODE>NC_BYTE</CODE>, <CODE>NC_CHAR</CODE>, <CODE>NC_SHORT</CODE>, <CODE>NC_INT</CODE>, <CODE>NC_FLOAT</CODE>, and <CODE>NC_DOUBLE</CODE>. <TR>
<TD><CODE>ndimsp</CODE><TD>Pointer to location for returned number of dimensions the variable was defined as using. For example, <CODE>2</CODE> indicates a matrix, <CODE>1 </CODE>indicates a vector, and <CODE>0</CODE> means the variable is a scalar with no dimensions. <TR>
<TD><CODE>dimids</CODE><TD>Returned <A NAME=MARKER-2-171></A>vector of <CODE>*ndimsp</CODE> dimension IDs corresponding to the variable dimensions. The caller must allocate enough space for a vector of at least <CODE>*ndimsp</CODE> integers to be returned. The maximum possible number of dimensions for a variable is given by the predefined constant <CODE><A NAME=MARKER-2-172></A>NC_MAX_VAR_DIMS</CODE>. <TR>
<TD><CODE>nattsp</CODE><TD>Pointer to location for returned number of variable attributes assigned to this variable.</TABLE>
</PRE>
Errors <A NAME=MARKER-10-2556></A><P>
These functions return the value <CODE>NC_NOERR <A NAME=MARKER-10-2557></A></CODE>if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-97></A>
<H4>Example </H4>
Here <A NAME=MARKER-2-2558></A>is an example using <CODE>nc_inq_var</CODE> <A NAME=MARKER-10-2559></A>to find out about a variable named <CODE>rh</CODE> in an existing netCDF dataset named <CODE>foo.nc</CODE>:<P>
<PRE>
#include <netcdf.h>
...
int status /* error status */
int ncid; /* netCDF ID */
int rh_id; /* variable ID */
nc_type rh_type; /* variable type */
int rh_ndims; /* number of dims */
int rh_dims[NC_MAX_VAR_DIMS]; /* variable shape */
int rh_natts /* number of attributes */
...
status = nc_open ("foo.nc", NC_NOWRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid (ncid, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
/* we don't need name, since we already know it */
status = nc_inq_var (ncid, rh_id, 0, &rh_type, &rh_ndims, rh_dims,
&rh_natts);
if (status != NC_NOERR) handle_error(status);
</PRE>
<A NAME=HEADING12-117></A>
<H2>7.5 <A NAME=MARKER-10-2560></A>Write a Single Data Value: <CODE><A NAME=MARKER-2-2561></A>nc_put_var1_<I>type</I></CODE> <CODE><A NAME=MARKER-10-2562></A><I></I></CODE></H2>
<HR>
The <A NAME=MARKER-2-2563></A><A NAME=MARKER-2-2564></A><A NAME=MARKER-2-2565></A><A NAME=MARKER-2-2566></A>functions <CODE>nc_put_var1_<B>type <A NAME=MARKER-10-2567></A></B></CODE>put a single data value of the specified <B>type</B> into a variable of an open netCDF dataset that is in data mode. Inputs are the netCDF ID, the variable ID, an index that specifies which value to add or alter, and the data value. The value is converted to the external data type of the variable, if necessary.<P>
<A NAME=HEADING12-119></A>
<H4>Usage </H4>
<PRE>
int nc_put_var1_text (int ncid, int varid, const size_t index[],
const char *tp);
int nc_put_var1_uchar (int ncid, int varid, const size_t index[],
const unsigned char *up);
int nc_put_var1_schar (int ncid, int varid, const size_t index[],
const signed char *cp);
int nc_put_var1_short (int ncid, int varid, const size_t index[],
const short *sp);
int nc_put_var1_int (int ncid, int varid, const size_t index[],
const int *ip);
int nc_put_var1_long (int ncid, int varid, const size_t index[],
const long *lp);
int nc_put_var1_float (int ncid, int varid, const size_t index[],
const float *fp);
int nc_put_var1_double(int ncid, int varid, const size_t index[],
const double *dp);
<TABLE BORDER="1"><TD><CODE>ncid</CODE><TD>NetCDF ID, from a previous call to <CODE>nc_open</CODE> or <CODE>nc_create</CODE>.<TR>
<TD><CODE>varid</CODE><TD>Variable ID.<TR>
<TD><CODE>index[]</CODE><TD>The index of the data value to be written. The indices are relative to 0, so for example, the first data value of a two-dimensional variable would have index <CODE>(0,0)</CODE>. The elements of <CODE>index</CODE> must correspond to the variable's dimensions. Hence, if the variable uses the unlimited dimension, the first index would correspond to the unlimited dimension.<TR>
<TD><CODE>tp, up, cp, sp, ip, lp, fp, </CODE>or<CODE> dp</CODE><TD>Pointer to the data value to be written. If the type of data values differs from the netCDF variable type, type conversion will occur. <A HREF=guidec-8.html#MARKER-9-1913>See Section 3.3 "Type Conversion," page 20</A>, for details.</TABLE>
</PRE>
Errors <A NAME=MARKER-10-2568></A><P>
<CODE>nc_put_var1_<B>type</B></CODE> <A NAME=MARKER-10-2569></A>returns the value <CODE>NC_NOERR <A NAME=MARKER-10-2570></A></CODE>if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>The specified indices were out of range for the rank of the specified variable. For example, a negative index or an index that is larger than the corresponding dimension length will cause an error. <P>
<LI>The specified value is out of the range of values representable by the external data type of the variable.<P>
<LI>The specified netCDF is in define mode rather than data mode.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-142></A>
<H4>Example </H4>
Here <A NAME=MARKER-2-2571></A>is an example using <CODE>nc_put_var1_double</CODE> to set the <CODE>(1,2,3)</CODE> element of the variable named <CODE>rh</CODE> to <CODE>0.5</CODE> in an existing netCDF dataset named <CODE>foo.nc</CODE>. For simplicity in this example, we assume that we know that <CODE>rh</CODE> is dimensioned with <CODE>time</CODE>, <CODE>lat</CODE>, and <CODE>lon</CODE>, so we want to set the value of <CODE>rh</CODE> that corresponds to the second <CODE>time</CODE> value, the third <CODE>lat</CODE> value, and the fourth <CODE>lon</CODE> value: <P>
<PRE>
#include <netcdf.h>
...
int status; /* error status */
int ncid; /* netCDF ID */
int rh_id; /* variable ID */
static size_t rh_index[] = {1, 2, 3}; /* where to put value */
static double rh_val = 0.5; /* value to put */
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid (ncid, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
...
status = nc_put_var1_double(ncid, rh_id, rh_index, &rh_val);
if (status != NC_NOERR) handle_error(status);
</PRE>
<A NAME=HEADING12-160></A>
<H2>7.6 <A NAME=MARKER-10-2572></A><A NAME=MARKER-2-2573></A><A NAME=MARKER-2-2574></A><A NAME=MARKER-2-2575></A><A NAME=MARKER-2-2576></A>Write an Entire Variable: <CODE><A NAME=MARKER-2-2577></A>nc_put_var_<I>type<A NAME=MARKER-10-2578></A></I></CODE></H2>
<HR>
The <CODE>nc_put_var_<B>type</B></CODE> <A NAME=MARKER-10-2579></A>family of functions write all the values of a variable into a netCDF variable of an open netCDF dataset. This is the simplest interface to use for writing a value in a scalar variable or whenever all the values of a multidimensional variable can all be written at once. The values to be written are associated with the netCDF variable by assuming that the last <A NAME=MARKER-10-2580></A>dimension of the netCDF variable varies fastest in the C <A NAME=MARKER-10-2581></A>interface. The values are converted to the external data type of the variable, if necessary.<P>
<A NAME=HEADING12-162></A>
<H4>Usage </H4>
<PRE>
int nc_put_var_text (int ncid, int varid, const char *tp);
int nc_put_var_uchar (int ncid, int varid, const unsigned char *up);
int nc_put_var_schar (int ncid, int varid, const signed char *cp);
int nc_put_var_short (int ncid, int varid, const short *sp);
int nc_put_var_int (int ncid, int varid, const int *ip);
int nc_put_var_long (int ncid, int varid, const long *lp);
int nc_put_var_float (int ncid, int varid, const float *fp);
int nc_put_var_double(int ncid, int varid, const double *dp);
<TABLE BORDER="1"><TD><CODE>ncid</CODE><TD>NetCDF ID, from a previous call to <CODE>nc_open</CODE> or <CODE>nc_create</CODE>.<TR>
<TD><CODE>varid</CODE><TD>Variable ID.<TR>
<TD><CODE>tp, up, cp, sp, ip, lp, fp, or dp</CODE><TD>Pointer to a block of data values to be written. The order in which the data will be written to the netCDF variable is with the last dimension of the specified variable varying fastest. If the type of data values differs from the netCDF variable type, type conversion will occur. <A HREF=guidec-8.html#MARKER-9-1913>See Section 3.3 "Type Conversion," page 20</A>, for details.</TABLE>
</PRE>
Errors <A NAME=MARKER-10-2582></A><P>
Members of the <CODE>nc_put_var_<B>type</B></CODE> <A NAME=MARKER-10-2583></A>family return the value <CODE>NC_NOERR <A NAME=MARKER-10-2584></A></CODE>if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>One or more of the specified values are out of the range of values representable by the external data type of the variable.<P>
<LI>One or more of the specified values are out of the range of values representable by the external data type of the variable.<P>
<LI>The specified netCDF dataset is in define mode rather than data mode.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-178></A>
<H4>Example </H4>
Here is an example using <CODE>nc_put_var_double</CODE> to add or change all the values of the variable named <CODE>rh</CODE> to <CODE>0.5</CODE> in an existing netCDF dataset named <CODE>foo.nc</CODE>. For simplicity in this example, we assume that we know that <CODE>rh</CODE> is dimensioned with <CODE>time</CODE>, <CODE>lat</CODE>, and <CODE>lon</CODE>, and that there are three <CODE>time</CODE> values, five <CODE>lat</CODE> values, and ten <CODE>lon</CODE> values. <P>
<PRE>
#include <netcdf.h>
...
#define TIMES 3
#define LATS 5
#define LONS 10
int status; /* error status */
int ncid; /* netCDF ID */
int rh_id; /* variable ID */
double rh_vals[TIMES*LATS*LONS]; /* array to hold values */
int i;
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid (ncid, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
...
for (i = 0; i < TIMES*LATS*LONS; i++)
rh_vals[i] = 0.5;
/* write values into netCDF variable */
status = nc_put_var_double(ncid, rh_id, rh_vals);
if (status != NC_NOERR) handle_error(status);
</PRE>
<A NAME=HEADING12-202></A>
<H2>7.7 <A NAME=MARKER-10-2586></A><A NAME=MARKER-2-2587></A><A NAME=MARKER-2-2588></A><A NAME=MARKER-2-2589></A><A NAME=MARKER-2-2590></A>Write an Array of Values: <CODE><A NAME=MARKER-2-2591></A>nc_put_vara<I>_type</I></CODE> <A NAME=MARKER-10-2592></A><I></I></H2>
<HR>
The function <CODE>nc_put_vara_<B>type</B></CODE> <A NAME=MARKER-10-2593></A>writes values into a netCDF variable of an open netCDF dataset. The part of the netCDF variable to write is specified by giving a corner and a vector of edge lengths that refer to an array section of the netCDF variable. The values to be written are associated with the netCDF variable by assuming that the last <A NAME=MARKER-10-2594></A>dimension of the netCDF variable varies fastest in the C <A NAME=MARKER-10-2595></A>interface. The netCDF dataset must be in data mode. <P>
<A NAME=HEADING12-204></A>
<H4>Usage </H4>
<PRE>
int nc_put_vara_<B>type</B> (int ncid, int varid, const size_t start[],
const size_t count[], const <B>type</B> *valuesp);
int nc_put_vara_text (int ncid, int varid, const size_t start[],
const size_t count[], const char *tp);
int nc_put_vara_uchar (int ncid, int varid, const size_t start[],
const size_t count[], const unsigned char *up);
int nc_put_vara_schar (int ncid, int varid, const size_t start[],
const size_t count[], const signed char *cp);
int nc_put_vara_short (int ncid, int varid, const size_t start[],
const size_t count[], const short *sp);
int nc_put_vara_int (int ncid, int varid, const size_t start[],
const size_t count[], const int *ip);
int nc_put_vara_long (int ncid, int varid, const size_t start[],
const size_t count[], const long *lp);
int nc_put_vara_float (int ncid, int varid, const size_t start[],
const size_t count[], const float *fp);
int nc_put_vara_double(int ncid, int varid, const size_t start[],
const size_t count[], const double *dp);
<TABLE BORDER="1"><TD><CODE>ncid</CODE><TD>NetCDF ID, from a previous call to <CODE>nc_open</CODE> or <CODE>nc_create</CODE>.<TR>
<TD><CODE>varid</CODE><TD>Variable ID.<TR>
<TD><CODE>start</CODE><TD>A vector of size_t integers specifying the index in the variable where the first of the data values will be written. The indices are relative to 0, so for example, the first data value of a variable would have index <CODE>(0, 0, ... , 0)</CODE>. The size of <CODE>start</CODE> must be the same as the number of dimensions of the specified variable. The elements of <CODE>start</CODE> must correspond to the variable's dimensions in order. Hence, if the variable is a record variable, the first index would correspond to the starting record number for writing the data values. <TR>
<TD><CODE>count</CODE><TD>A vector of size_t integers specifying the edge lengths along each dimension of the block of data values to be written. To write a single value, for example, specify <CODE>count</CODE> as <CODE>(1, 1, ... , 1)</CODE>. The length of <CODE>count</CODE> is the number of dimensions of the specified variable. The elements of <CODE>count </CODE>correspond to the variable's dimensions. Hence, if the variable is a record variable, the first element of <CODE>count</CODE> corresponds to a count of the number of records to write. <TR>
<TD><CODE>tp, up, cp, sp, ip, lp, fp, or dp</CODE><TD>Pointer to a block of data values to be written. The order in which the data will be written to the netCDF variable is with the last dimension of the specified variable varying fastest. If the type of data values differs from the netCDF variable type, type conversion will occur. <A HREF=guidec-8.html#MARKER-9-1913>See Section 3.3 "Type Conversion," page 20</A>, for details.</TABLE>
</PRE>
Errors <A NAME=MARKER-10-2596></A><P>
<CODE>nc_put_vara_<B>type</B></CODE> <A NAME=MARKER-10-2597></A>returns the value <CODE>NC_NOERR <A NAME=MARKER-10-2598></A></CODE>if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>The specified corner indices were out of range for the rank of the specified variable. For example, a negative index, or an index that is larger than the corresponding dimension length will cause an error. <P>
<LI>The specified edge lengths added to the specified corner would have referenced data out of range for the rank of the specified variable. For example, an edge length that is larger than the corresponding dimension length minus the corner index will cause an error. <P>
<LI>One or more of the specified values are out of the range of values representable by the external data type of the variable.<P>
<LI>The specified netCDF dataset is in define mode rather than data mode.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-231></A>
<H4>Example </H4>
Here <A NAME=MARKER-2-2599></A>is an example using <CODE>nc_put_vara_double</CODE> to add or change all the values of the variable named <CODE>rh</CODE> to <CODE>0.5</CODE> in an existing netCDF dataset named <CODE>foo.nc</CODE>. For simplicity in this example, we assume that we know that <CODE>rh</CODE> is dimensioned with <CODE>time</CODE>, <CODE>lat</CODE>, and <CODE>lon</CODE>, and that there are three <CODE>time</CODE> values, five <CODE>lat</CODE> values, and ten <CODE>lon</CODE> values. <P>
<PRE>
#include <netcdf.h>
...
#define TIMES 3
#define LATS 5
#define LONS 10
int status; /* error status */
int ncid; /* netCDF ID */
int rh_id; /* variable ID */
static size_t start[] = {0, 0, 0}; /* start at first value */
static size_t count[] = {TIMES, LATS, LONS};
double rh_vals[TIMES*LATS*LONS]; /* array to hold values */
int i;
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid (ncid, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
...
for (i = 0; i < TIMES*LATS*LONS; i++)
rh_vals[i] = 0.5;
/* write values into netCDF variable */
status = nc_put_vara_double(ncid, rh_id, start, count, rh_vals);
if (status != NC_NOERR) handle_error(status);
</PRE>
<A NAME=HEADING12-257></A>
<H2>7.8 <A NAME=MARKER-10-2600></A><A NAME=MARKER-2-2601></A><A NAME=MARKER-2-2602></A><A NAME=MARKER-2-2603></A><A NAME=MARKER-2-2604></A>Write a Subsampled Array of Values: <CODE><A NAME=MARKER-2-2605></A>nc_put_vars_<I>type</I></CODE> <CODE><A NAME=MARKER-10-2606></A><B></B></CODE></H2>
<HR>
Each member of the family of functions <CODE>nc_put_vars_<B>type</B></CODE> <A NAME=MARKER-10-2607></A>writes a subsampled (strided) array section of values into a netCDF variable of an open netCDF dataset. The subsampled array section is specified by giving a corner, a vector of counts, and a stride vector. The netCDF dataset must be in data mode. <P>
<A NAME=HEADING12-259></A>
<H4>Usage </H4>
<PRE>
int nc_put_vars_text (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const char *tp);
int nc_put_vars_uchar (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const unsigned char *up);
int nc_put_vars_schar (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const signed char *cp);
int nc_put_vars_short (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const short *sp);
int nc_put_vars_int (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const int *ip);
int nc_put_vars_long (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const long *lp);
int nc_put_vars_float (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const float *fp);
int nc_put_vars_double(int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const double *dp);
<TABLE BORDER="1"><TD><CODE>ncid</CODE><TD>NetCDF ID, from a previous call to <CODE>nc_open</CODE> or <CODE>nc_create</CODE>.<TR>
<TD><CODE>varid</CODE><TD>Variable ID.<TR>
<TD><CODE>start</CODE><TD>A vector of size_t integers specifying the index in the variable where the first of the data values will be written. The indices are relative to 0, so for example, the first data value of a variable would have index <CODE>(0, 0, ... , 0)</CODE>. The elements of <CODE>start</CODE> correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the first index corresponds to the starting record number for writing the data values. <TR>
<TD><CODE>count</CODE><TD>A vector of size_t integers specifying the number of indices selected along each dimension. To write a single value, for example, specify <CODE>count</CODE> as <CODE>(1, 1, ... , 1)</CODE>. The elements of <CODE>count</CODE> correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the first element of <CODE>count</CODE> corresponds to a count of the number of records to write. <TR>
<TD><CODE>stride</CODE><TD>A vector of ptrdiff_t integers that specifies the sampling interval along each dimension of the netCDF variable. The elements of the stride vector correspond, in order, to the netCDF variable's dimensions (stride[0] gives the sampling interval along the most slowly varying dimension of the netCDF variable). Sampling intervals are specified in type-independent units of elements (a value of 1 selects consecutive elements of the netCDF variable along the corresponding dimension, a value of 2 selects every other element, etc.). A <CODE>NULL</CODE> stride argument is treated as <CODE>(1, 1, ... , 1)</CODE>. <TR>
<TD><CODE>tp, up, cp, sp, ip, lp, fp, or dp</CODE><TD>Pointer to a block of data values to be written. The order in which the data will be written to the netCDF variable is with the last dimension of the specified variable varying fastest. If the type of data values differs from the netCDF variable type, type conversion will occur. <A HREF=guidec-8.html#MARKER-9-1913>See Section 3.3 "Type Conversion," page 20</A>, for details.</TABLE>
</PRE>
Errors <A NAME=MARKER-10-2610></A><P>
<CODE>nc_put_vars_<B>type</B></CODE> <A NAME=MARKER-10-2611></A>returns the value <CODE>NC_NOERR <A NAME=MARKER-10-2612></A></CODE>if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>The specified start, count and stride generate an index which is out of range.<P>
<LI>One or more of the specified values are out of the range of values representable by the external data type of the variable.<P>
<LI>The specified netCDF is in define mode rather than data mode.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-291></A>
<H4>Example </H4>
Here is an example of using <CODE>nc_put_vars_float</CODE> <A NAME=MARKER-10-2613></A>to write -- from an internal array -- every other point of a netCDF variable named <CODE>rh</CODE> which is described by the C <A NAME=MARKER-10-2614></A>declaration <CODE>float rh[4][6]</CODE> <A NAME=MARKER-10-2615></A>(note the size of the dimensions):<P>
<PRE>
#include <netcdf.h>
...
#define NDIM 2 /* rank of netCDF variable */
int ncid; /* netCDF ID */
int status; /* error status */
int rhid; /* variable ID */
static size_t start[NDIM] /* netCDF variable start point: */
= {0, 0}; /* first element */
static size_t count[NDIM] /* size of internal array: entire */
= {2, 3}; /* (subsampled) netCDF variable */
static ptrdiff_t stride[NDIM] /* variable subsampling intervals: */
= {2, 2}; /* access every other netCDF element */
float rh[2][3]; /* note subsampled sizes for */
/* netCDF variable dimensions */
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid(ncid, "rh", &rhid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_put_vars_float(ncid, rhid, start, count, stride, rh);
if (status != NC_NOERR) handle_error(status);
</PRE>
<A NAME=HEADING12-316></A>
<H2>7.9 <A NAME=MARKER-10-2616></A><A NAME=MARKER-9-2617></A>Write a Mapped Array of Values: <CODE><A NAME=MARKER-2-2618></A>nc_put_varm_type <A NAME=MARKER-10-2619></A></CODE></H2>
<HR>
The <CODE>nc_put_varm_<B>type <A NAME=MARKER-10-2620></A></B></CODE><A NAME=MARKER-2-2621></A><A NAME=MARKER-2-2622></A><A NAME=MARKER-2-2623></A><A NAME=MARKER-2-2624></A>family of functions writes a mapped array section of values into a netCDF variable of an open netCDF dataset. The mapped array section is specified by giving a corner, a vector of counts, a stride vector, and an index mapping vector. The index mapping vector is a vector of integers that specifies the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. No assumptions are made about the ordering or length of the dimensions of the data array. The netCDF dataset must be in data mode. <P>
<A NAME=HEADING12-318></A>
<H4>Usage </H4>
<PRE>
int nc_put_varm_text (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], const char *tp);
int nc_put_varm_uchar (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], const unsigned char *up);
int nc_put_varm_schar (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], const signed char *cp);
int nc_put_varm_short (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], const short *sp);
int nc_put_varm_int (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], const int *ip);
int nc_put_varm_long (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], const long *lp);
int nc_put_varm_float (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], const float *fp);
int nc_put_varm_double(int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], const double *dp);
<TABLE BORDER="1"><TD><CODE>ncid</CODE><TD>NetCDF ID, from a previous call to <CODE>nc_open</CODE> or <CODE>nc_create</CODE>.<TR>
<TD><CODE>varid</CODE><TD>Variable ID.<TR>
<TD><CODE>start</CODE><TD>A vector of size_t integers specifying the index in the variable where the first of the data values will be written. The indices are relative to 0, so for example, the first data value of a variable would have index <CODE>(0, 0, ... , 0)</CODE>. The elements of <CODE>start</CODE> correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the first index corresponds to the starting record number for writing the data values. <TR>
<TD><CODE>count</CODE><TD>A vector of size_t integers specifying the number of indices selected along each dimension. To write a single value, for example, specify <CODE>count</CODE> as <CODE>(1, 1, ... , 1)</CODE>. The elements of <CODE>count</CODE> correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the first element of <CODE>count</CODE> corresponds to a count of the number of records to write. <TR>
<TD><CODE>stride</CODE><TD>A vector of ptrdiff_t integers that specifies the sampling interval along each dimension of the netCDF variable. The elements of the stride vector correspond, in order, to the netCDF variable's dimensions (stride[0] gives the sampling interval along the most slowly varying dimension of the netCDF variable). Sampling intervals are specified in type-independent units of elements (a value of 1 selects consecutive elements of the netCDF variable along the corresponding dimension, a value of 2 selects every other element, etc.). A <CODE>NULL</CODE> stride argument is treated as <CODE>(1, 1, ... , 1)</CODE>. <TR>
<TD><CODE>imap</CODE><TD>A vector of ptrdiff_t integers that specifies the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. The elements of the index mapping vector correspond, in order, to the netCDF variable's dimensions (imap[0] gives the distance between elements of the internal array corresponding to the most slowly varying dimension of the netCDF variable). Distances between elements are specified in type-independent units of elements (the distance between internal elements that occupy adjacent memory locations is 1 and not the element's byte-length as in netCDF 2). A <CODE>NULL</CODE> argument means the memory-resident values have the same structure as the associated netCDF variable. <TR>
<TD><CODE>tp, up, cp, sp, ip, lp, fp, or dp</CODE><TD>Pointer to the location used for computing where the data values will be found; the data should be of the type appropriate for the function called. If the type of data values differs from the netCDF variable type, type conversion will occur. <A HREF=guidec-8.html#MARKER-9-1913>See Section 3.3 "Type Conversion," page 20</A>, for details.</TABLE>
</PRE>
Errors <A NAME=MARKER-10-2633></A><P>
<CODE>nc_put_varm_<B>type <A NAME=MARKER-10-2634></A></B></CODE>returns the value <CODE>NC_NOERR <A NAME=MARKER-10-2635></A></CODE>if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>The specified <CODE>start</CODE>,<A NAME=MARKER-10-2636></A> <CODE>count</CODE>,<A NAME=MARKER-10-2637></A> and <CODE>stride</CODE> <A NAME=MARKER-10-2638></A>generate an index which is out of range. Note that no error checking is possible on the <CODE>imap</CODE> <A NAME=MARKER-10-2639></A>vector.<P>
<LI>One or more of the specified values are out of the range of values representable by the external data type of the variable.<P>
<LI>The specified netCDF is in define mode rather than data mode.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-351></A>
<H4>Example </H4>
The following <CODE>imap <A NAME=MARKER-10-2640></A></CODE>vector maps in the trivial way a 4x3x2 <A NAME=MARKER-10-2641></A>netCDF variable and an internal array of the same shape: <P>
<PRE>
float a[4][3][2]; /* same shape as netCDF variable */
int imap[3] = {6, 2, 1};
/* netCDF dimension inter-element distance */
/* ---------------- ---------------------- */
/* most rapidly varying 1 */
/* intermediate 2 (=imap[2]*2) */
/* most slowly varying 6 (=imap[1]*3) */
</PRE>
<A NAME=MARKER-10-2642></A>Using the <CODE>imap</CODE> <A NAME=MARKER-10-2643></A>vector above with <CODE>nc_put_varm_float</CODE> <A NAME=MARKER-10-2644></A>obtains the same result as simply using <CODE>nc_put_var_float</CODE>.<A NAME=MARKER-10-2645></A><P>
Here is an example of using <CODE>nc_put_varm_float</CODE> <A NAME=MARKER-10-2646></A>to write -- from a transposed, internal array -- a netCDF variable named <CODE>rh</CODE> which is described by the C <A NAME=MARKER-10-2647></A>declaration <CODE>float rh[6][4]</CODE> <A NAME=MARKER-10-2648></A>(note the size and order of the dimensions):<P>
<PRE>
#include <netcdf.h>
...
#define NDIM 2 /* rank of netCDF variable */
int ncid; /* netCDF ID */
int status; /* error status */
int rhid; /* variable ID */
static size_t start[NDIM] /* netCDF variable start point: */
= {0, 0}; /* first element */
static size_t count[NDIM] /* size of internal array: entire netCDF */
= {6, 4}; /* variable; order corresponds to netCDF */
/* variable -- not internal array */
static ptrdiff_t stride[NDIM]/* variable subsampling intervals: */
= {1, 1}; /* sample every netCDF element */
static ptrdiff_t imap[NDIM] /* internal array inter-element distances; */
= {1, 6}; /* would be {4, 1} if not transposing */
float rh[4][6]; /* note transposition of netCDF variable */
/* dimensions */
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid(ncid, "rh", &rhid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_put_varm_float(ncid, rhid, start, count, stride, imap, rh);
if (status != NC_NOERR) handle_error(status);
</PRE>
<A NAME=MARKER-10-2649></A>Here is another example of using <CODE>nc_put_varm_float</CODE> <A NAME=MARKER-10-2650></A>to write -- from a transposed, internal array -- a subsample of the same netCDF variable, by writing every other point of the netCDF variable:<P>
<PRE>
#include <netcdf.h>
...
#define NDIM 2 /* rank of netCDF variable */
int ncid; /* netCDF ID */
int status; /* error status */
int rhid; /* variable ID */
static size_t start[NDIM] /* netCDF variable start point: */
= {0, 0}; /* first element */
static size_t count[NDIM] /* size of internal array: entire */
= {3, 2}; /* (subsampled) netCDF variable; order of */
/* dimensions corresponds to netCDF */
/* variable -- not internal array */
static ptrdiff_t stride[NDIM] /* variable subsampling intervals: */
= {2, 2}; /* sample every other netCDF element */
static ptrdiff_t imap[NDIM] /* internal array inter-element distances; */
= {1, 3}; /* would be {2, 1} if not transposing */
float rh[2][3]; /* note transposition of (subsampled) */
/* netCDF variable dimensions */
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid(ncid, "rh", &rhid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_put_varm_float(ncid, rhid, start, count, stride, imap, rh);
if (status != NC_NOERR) handle_error(status);
</PRE>
<A NAME=HEADING12-416></A>
<H2>7.10 <A NAME=MARKER-10-2651></A>Read a Single Data Value: <CODE><A NAME=MARKER-2-2652></A>nc_get_var1_<I>type</I></CODE> <A NAME=MARKER-10-2653></A><I></I></H2>
<HR>
The <A NAME=MARKER-2-2654></A><A NAME=MARKER-2-2655></A><A NAME=MARKER-2-2656></A><A NAME=MARKER-2-2657></A>functions <CODE>nc_get_var1_<B>type</B></CODE> <A NAME=MARKER-10-2658></A>get a single data value from a variable of an open netCDF dataset that is in data mode. Inputs are the netCDF ID, the variable ID, a multidimensional index that specifies which value to get, and the address of a location into which the data value will be read. The value is converted from the external data type of the variable, if necessary.<P>
<A NAME=HEADING12-418></A>
<H4>Usage </H4>
<PRE>
int nc_get_var1_text (int ncid, int varid, const size_t index[],
char *tp);
int nc_get_var1_uchar (int ncid, int varid, const size_t index[],
unsigned char *up);
int nc_get_var1_schar (int ncid, int varid, const size_t index[],
signed char *cp);
int nc_get_var1_short (int ncid, int varid, const size_t index[],
short *sp);
int nc_get_var1_int (int ncid, int varid, const size_t index[],
int *ip);
int nc_get_var1_long (int ncid, int varid, const size_t index[],
long *lp);
int nc_get_var1_float (int ncid, int varid, const size_t index[],
float *fp);
int nc_get_var1_double(int ncid, int varid, const size_t index[],
double *dp);
<TABLE BORDER="1"><TD><CODE>ncid</CODE><TD>NetCDF ID, from a previous call to <CODE>nc_open</CODE> or <CODE>nc_create</CODE>.<TR>
<TD><CODE>varid</CODE><TD>Variable ID.<TR>
<TD><CODE>index[]</CODE><TD>The index of the data value to be read. The indices are relative to 0, so for example, the first data value of a two-dimensional variable would have index <CODE>(0,0)</CODE>. The elements of <CODE>index</CODE> must correspond to the variable's dimensions. Hence, if the variable is a record variable, the first index is the record number. <TR>
<TD><CODE>tp, up, cp, sp, ip, lp, fp, </CODE>or<CODE>, dp</CODE><TD>Pointer to the location into which the data value is read. If the type of data value differs from the netCDF variable type, type conversion will occur. <A HREF=guidec-8.html#MARKER-9-1913>See Section 3.3 "Type Conversion," page 20</A>, for details.</TABLE>
</PRE>
Errors <A NAME=MARKER-10-2659></A><P>
<CODE>nc_get_var1_<B>type</B></CODE> <A NAME=MARKER-10-2660></A>returns the value <CODE>NC_NOERR <A NAME=MARKER-10-2661></A></CODE>if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>The specified indices were out of range for the rank of the specified variable. For example, a negative index or an index that is larger than the corresponding dimension length will cause an error.<P>
<LI>The value is out of the range of values representable by the desired data type. <P>
<LI>The specified netCDF is in define mode rather than data mode.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-442></A>
<H4>Example </H4>
Here <A NAME=MARKER-2-2662></A>is an example using <CODE>nc_get_var1_double</CODE> to get the <CODE>(1,2,3)</CODE> element of the variable named <CODE>rh</CODE> in an existing netCDF dataset named <CODE>foo.nc</CODE>. For simplicity in this example, we assume that we know that <CODE>rh</CODE> is dimensioned with <CODE>time</CODE>, <CODE>lat</CODE>, and <CODE>lon</CODE>, so we want to get the value of <CODE>rh</CODE> that corresponds to the second <CODE>time</CODE> value, the third <CODE>lat</CODE> value, and the fourth <CODE>lon</CODE> value: <P>
<PRE>
#include <netcdf.h>
...
int status; /* error status */
int ncid; /* netCDF ID */
int rh_id; /* variable ID */
static size_t rh_index[] = {1, 2, 3}; /* where to get value from */
double rh_val; /* where to put it */
...
status = nc_open("foo.nc", NC_NOWRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid (ncid, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
...
status = nc_get_var1_double(ncid, rh_id, rh_index, &rh_val);
if (status != NC_NOERR) handle_error(status);
</PRE>
<A NAME=HEADING12-460></A>
<H2>7.11 <A NAME=MARKER-10-2663></A>Read an Entire Variable <CODE><A NAME=MARKER-2-2664></A>nc_get_var_type <A NAME=MARKER-10-2665></A><I></I></CODE></H2>
<HR>
The <A NAME=MARKER-2-2666></A><A NAME=MARKER-2-2667></A><A NAME=MARKER-2-2668></A>members of the <CODE>nc_get_var_<B>type</B></CODE> <A NAME=MARKER-10-2669></A>family of functions read all the values from a netCDF variable of an open netCDF dataset. This is the simplest interface to use for reading the value of a scalar variable or when all the values of a multidimensional variable can be read at once. The values are read into consecutive locations with the last <A NAME=MARKER-10-2670></A>dimension varying fastest. The netCDF dataset must be in data mode.<P>
<A NAME=HEADING12-462></A>
<H4>Usage </H4>
<PRE>
int nc_get_var_text (int ncid, int varid, char *tp);
int nc_get_var_uchar (int ncid, int varid, unsigned char *up);
int nc_get_var_schar (int ncid, int varid, signed char *cp);
int nc_get_var_short (int ncid, int varid, short *sp);
int nc_get_var_int (int ncid, int varid, int *ip);
int nc_get_var_long (int ncid, int varid, long *lp);
int nc_get_var_float (int ncid, int varid, float *fp);
int nc_get_var_double(int ncid, int varid, double *dp);
<TABLE BORDER="1"><TD><CODE>ncid</CODE><TD>NetCDF ID, from a previous call to <CODE>nc_open</CODE> or <CODE>nc_create</CODE>.<TR>
<TD><CODE>varid</CODE><TD>Variable ID.<TR>
<TD><CODE>tp, up, cp, sp, ip, lp, fp, </CODE>or<CODE> dp</CODE><TD>Pointer to the location into which the data value is read. If the type of data value differs from the netCDF variable type, type conversion will occur. <A HREF=guidec-8.html#MARKER-9-1913>See Section 3.3 "Type Conversion," page 20</A>, for details.</TABLE>
</PRE>
Errors <A NAME=MARKER-10-2671></A><P>
<CODE>nc_get_var_<B>type</B></CODE> <A NAME=MARKER-10-2672></A>returns the value <CODE>NC_NOERR <A NAME=MARKER-10-2673></A></CODE>if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>One or more of the values are out of the range of values representable by the desired type.<P>
<LI>The specified netCDF is in define mode rather than data mode.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-477></A>
<H4>Example </H4>
Here is an example using <CODE>nc_get_var_double</CODE> to read all the values of the variable named <CODE>rh</CODE> from an existing netCDF dataset named <CODE>foo.nc</CODE>. For simplicity in this example, we assume that we know that <CODE>rh</CODE> is dimensioned with <CODE>time</CODE>, <CODE>lat</CODE>, and <CODE>lon</CODE>, and that there are three <CODE>time</CODE> values, five <CODE>lat </CODE>values, and ten <CODE>lon</CODE> values. <P>
<PRE>
#include <netcdf.h>
...
#define TIMES 3
#define LATS 5
#define LONS 10
int status; /* error status */
int ncid; /* netCDF ID */
int rh_id; /* variable ID */
double rh_vals[TIMES*LATS*LONS]; /* array to hold values */
...
status = nc_open("foo.nc", NC_NOWRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid (ncid, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
...
/* read values from netCDF variable */
status = nc_get_var_double(ncid, rh_id, rh_vals);
if (status != NC_NOERR) handle_error(status);
</PRE>
<A NAME=MARKER-10-2675></A><P>
<A NAME=HEADING12-499></A>
<H2>7.12 Read an Array of Values: <CODE><A NAME=MARKER-2-2676></A>nc_get_vara_type <A NAME=MARKER-10-2677></A><I></I></CODE></H2>
<HR>
The <A NAME=MARKER-2-2678></A><A NAME=MARKER-2-2679></A><A NAME=MARKER-2-2680></A><A NAME=MARKER-2-2681></A>members of the <CODE>nc_get_vara_<B>type</B></CODE> <A NAME=MARKER-10-2682></A>family of functions read an array of values from a netCDF variable of an open netCDF dataset. The array is specified by giving a corner and a vector of edge lengths. The values are read into consecutive locations with the last <A NAME=MARKER-10-2683></A>dimension varying fastest. The netCDF dataset must be in data mode.<P>
<A NAME=HEADING12-501></A>
<H4>Usage </H4>
<PRE>
int nc_get_vara_text (int ncid, int varid, const size_t start[],
const size_t count[] char *tp);
int nc_get_vara_uchar (int ncid, int varid, const size_t start[],
const size_t count[] unsigned char *up);
int nc_get_vara_schar (int ncid, int varid, const size_t start[],
const size_t count[] signed char *cp);
int nc_get_vara_short (int ncid, int varid, const size_t start[],
const size_t count[] short *sp);
int nc_get_vara_int (int ncid, int varid, const size_t start[],
const size_t count[] int *ip);
int nc_get_vara_long (int ncid, int varid, const size_t start[],
const size_t count[] long *lp);
int nc_get_vara_float (int ncid, int varid, const size_t start[],
const size_t count[] float *fp);
int nc_get_vara_double(int ncid, int varid, const size_t start[],
const size_t count[] double *dp);
<TABLE BORDER="1"><TD><CODE>ncid</CODE><TD>NetCDF ID, from a previous call to <CODE>nc_open</CODE> or <CODE>nc_create</CODE>.<TR>
<TD><CODE>varid</CODE><TD>Variable ID.<TR>
<TD><CODE>start</CODE><TD>A vector of size_t integers specifying the index in the variable where the first of the data values will be read. The indices are relative to 0, so for example, the first data value of a variable would have index <CODE>(0, 0, ... , 0)</CODE>. The length of <CODE>start</CODE> must be the same as the number of dimensions of the specified variable. The elements of <CODE>start</CODE> correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the first index would correspond to the starting record number for reading the data values. <TR>
<TD><CODE>count</CODE><TD>A vector of size_t integers specifying the edge lengths along each dimension of the block of data values to be read. To read a single value, for example, specify <CODE>count</CODE> as <CODE>(1, 1, ... , 1)</CODE>. The length of <CODE>count</CODE> is the number of dimensions of the specified variable. The elements of <CODE>count </CODE>correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the first element of <CODE>count</CODE> corresponds to a count of the number of records to read. <TR>
<TD><CODE>tp, up, cp, sp, ip, lp, fp, </CODE>or<CODE>, dp</CODE><TD>Pointer to the location into which the data value is read. If the type of data value differs from the netCDF variable type, type conversion will occur. <A HREF=guidec-8.html#MARKER-9-1913>See Section 3.3 "Type Conversion," page 20</A>, for details.</TABLE>
</PRE>
Errors <A NAME=MARKER-10-2684></A><P>
<CODE>nc_get_vara_<B>type</B></CODE> <A NAME=MARKER-10-2685></A>returns the value <CODE>NC_NOERR <A NAME=MARKER-10-2686></A></CODE>if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>The specified corner indices were out of range for the rank of the specified variable. For example, a negative index or an index that is larger than the corresponding dimension length will cause an error. <P>
<LI>The specified edge lengths added to the specified corner would have referenced data out of range for the rank of the specified variable. For example, an edge length that is larger than the corresponding dimension length minus the corner index will cause an error. <P>
<LI>One or more of the values are out of the range of values representable by the desired type.<P>
<LI>The specified netCDF is in define mode rather than data mode.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-526></A>
<H4>Example </H4>
Here <A NAME=MARKER-2-2687></A>is an example using <CODE>nc_get_vara_double</CODE> to read all the values of the variable named <CODE>rh</CODE> from an existing netCDF dataset named <CODE>foo.nc</CODE>. For simplicity in this example, we assume that we know that <CODE>rh</CODE> is dimensioned with <CODE>time</CODE>, <CODE>lat</CODE>, and <CODE>lon</CODE>, and that there are three <CODE>time</CODE> values, five <CODE>lat </CODE>values, and ten <CODE>lon</CODE> values. <P>
<PRE>
#include <netcdf.h>
...
#define TIMES 3
#define LATS 5
#define LONS 10
int status; /* error status */
int ncid; /* netCDF ID */
int rh_id; /* variable ID */
static size_t start[] = {0, 0, 0}; /* start at first value */
static size_t count[] = {TIMES, LATS, LONS};
double rh_vals[TIMES*LATS*LONS]; /* array to hold values */
...
status = nc_open("foo.nc", NC_NOWRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid (ncid, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
...
/* read values from netCDF variable */
status = nc_get_vara_double(ncid, rh_id, start, count, rh_vals);
if (status != NC_NOERR) handle_error(status);
</PRE>
<A NAME=HEADING12-549></A>
<H2>7.13 <A NAME=MARKER-10-2688></A>Read a Subsampled Array of Values: <CODE><A NAME=MARKER-2-2689></A>nc_get_vars<I>_type <A NAME=MARKER-10-2690></A></I></CODE></H2>
<HR>
<A NAME=MARKER-2-2691></A><A NAME=MARKER-2-2692></A><A NAME=MARKER-2-2693></A><A NAME=MARKER-2-2694></A><A NAME=MARKER-2-2695></A>The <CODE>nc_get_vars_<B>type</B></CODE> <A NAME=MARKER-10-2696></A>family of functions read a subsampled (strided) array section of values from a netCDF variable of an open netCDF dataset. The subsampled array section is specified by giving a corner, a vector of edge lengths, and a stride vector. The values are read with the last <A NAME=MARKER-10-2699></A>dimension of the netCDF variable varying fastest. The netCDF dataset must be in data mode. <P>
<A NAME=HEADING12-551></A>
<H4>Usage </H4>
<PRE>
int nc_get_vars_text (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
char *tp);
int nc_get_vars_uchar (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
unsigned char *up);
int nc_get_vars_schar (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
signed char *cp);
int nc_get_vars_short (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
short *sp);
int nc_get_vars_int (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
int *ip);
int nc_get_vars_long (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
long *lp);
int nc_get_vars_float (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
float *fp);
int nc_get_vars_double(int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
double *dp)
<TABLE BORDER="1"><TD><CODE>ncid</CODE><TD>NetCDF ID, from a previous call to <CODE>nc_open</CODE> or <CODE>nc_create</CODE>.<TR>
<TD><CODE>varid</CODE><TD>Variable ID.<TR>
<TD><CODE>start</CODE><TD>A vector of size_t integers specifying the index in the variable where the first of the data values will be read. The indices are relative to 0, so for example, the first data value of a variable would have index <CODE>(0, 0, ... , 0)</CODE>. The elements of <CODE>start </CODE>correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the first index corresponds to the starting record number for reading the data values. <TR>
<TD><CODE>count</CODE><TD>A vector of size_t integers specifying the number of indices selected along each dimension. To read a single value, for example, specify <CODE>count</CODE> as <CODE>(1, 1, ... , 1)</CODE>. The elements of <CODE>count</CODE> correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the first element of <CODE>count</CODE> corresponds to a count of the number of records to read. <TR>
<TD><CODE>stride</CODE><TD>A vector of ptrdiff_t integers specifying, for each dimension, the interval between selected indices. The elements of the stride vector correspond, in order, to the variable's dimensions. A value of 1 accesses adjacent values of the netCDF variable in the corresponding dimension; a value of 2 accesses every other value of the netCDF variable in the corresponding dimension; and so on. A <CODE>NULL</CODE> stride argument is treated as <CODE>(1, 1, ... , 1)</CODE>. <TR>
<TD><CODE>tp, up, cp, sp, ip, lp, fp, </CODE>or<CODE>, dp</CODE><TD>Pointer to the location into which the data value is read. If the type of data value differs from the netCDF variable type, type conversion will occur. <A HREF=guidec-8.html#MARKER-9-1913>See Section 3.3 "Type Conversion," page 20</A>, for details.</TABLE>
</PRE>
Errors <A NAME=MARKER-10-2700></A><P>
<CODE>nc_get_vars_<B>type</B></CODE> <A NAME=MARKER-10-2701></A>returns the value <CODE>NC_NOERR <A NAME=MARKER-10-2702></A></CODE>if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>The specified start, count and stride generate an index which is out of range.<P>
<LI>One or more of the values are out of the range of values representable by the desired type.<P>
<LI>The specified netCDF is in define mode rather than data mode.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-583></A>
<H4>Example </H4>
Here is an <A NAME=MARKER-2-2703></A>example that uses <CODE>nc_get_vars_double</CODE> to read every other value in each dimension of the variable named <CODE>rh</CODE> from an existing netCDF dataset named <CODE>foo.nc</CODE>. For simplicity in this example, we assume that we know that <CODE>rh</CODE> is dimensioned with <CODE>time</CODE>, <CODE>lat</CODE>, and <CODE>lon</CODE>, and that there are three <CODE>time</CODE> values, five <CODE>lat</CODE> values, and ten <CODE>lon</CODE> values. <P>
<PRE>
#include <netcdf.h>
...
#define TIMES 3
#define LATS 5
#define LONS 10
int status; /* error status */
int ncid; /* netCDF ID */
int rh_id; /* variable ID */
static size_t start[] = {0, 0, 0}; /* start at first value */
static size_t count[] = {TIMES, LATS, LONS};
static ptrdiff_t stride[] = {2, 2, 2};/* every other value */
double data[TIMES][LATS][LONS]; /* array to hold values */
...
status = nc_open("foo.nc", NC_NOWRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid (ncid, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
...
/* read subsampled values from netCDF variable into array */
status = nc_get_vars_double(ncid, rh_id, start, count, stride,
&data[0][0][0]);
if (status != NC_NOERR) handle_error(status);
...
</PRE>
<A NAME=HEADING12-609></A>
<H2>7.14 <A NAME=MARKER-10-2704></A><CODE><A NAME=MARKER-10-2705></A><A NAME=MARKER-10-2706></A></CODE>Read a Mapped Array of Values: <CODE><A NAME=MARKER-2-2707></A>nc_get_varm<I>_type</I></CODE> <CODE><A NAME=MARKER-10-2708></A><B></B></CODE></H2>
<HR>
<A NAME=MARKER-2-2709></A><A NAME=MARKER-2-2710></A><A NAME=MARKER-2-2711></A><A NAME=MARKER-2-2712></A><A NAME=MARKER-2-2713></A>The <CODE>nc_get_varm_<B>type</B></CODE> <A NAME=MARKER-10-2714></A>family of functions reads a mapped array section of values from a netCDF variable of an open netCDF dataset. The mapped array section is specified by giving a corner, a vector of edge lengths, a <A NAME=MARKER-2-2715></A><A NAME=MARKER-2-2716></A>stride vector, and an index mapping vector. The <A NAME=MARKER-2-2720></A><A NAME=MARKER-2-2721></A><A NAME=MARKER-2-2722></A>index mapping vector is a vector of integers that specifies the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. No assumptions are made about the ordering or length of the dimensions of the data array. The netCDF dataset must be in data mode. <P>
<A NAME=HEADING12-611></A>
<H4>Usage </H4>
<PRE>
int nc_get_varm_text (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], char *tp);
int nc_get_varm_uchar (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], unsigned char *up);
int nc_get_varm_schar (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], signed char *cp);
int nc_get_varm_short (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], short *sp);
int nc_get_varm_int (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], int *ip);
int nc_get_varm_long (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], long *lp);
int nc_get_varm_float (int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], float *fp);
int nc_get_varm_double(int ncid, int varid, const size_t start[],
const size_t count[], const ptrdiff_t stride[],
const ptrdiff_t imap[], double *dp);
<TABLE BORDER="1"><TD><CODE>ncid</CODE><TD>NetCDF ID, from a previous call to <CODE>nc_open</CODE> or <CODE>nc_create</CODE>.<TR>
<TD><CODE>varid</CODE><TD>Variable ID.<TR>
<TD><CODE>start</CODE><TD>A vector of size_t integers specifying the index in the variable where the first of the data values will be read. The indices are relative to 0, so for example, the first data value of a variable would have index <CODE>(0, 0, ... , 0)</CODE>. The elements of <CODE>start </CODE>correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the first index corresponds to the starting record number for reading the data values. <TR>
<TD><CODE>count</CODE><TD>A vector of size_t integers specifying the number of indices selected along each dimension. To read a single value, for example, specify <CODE>count</CODE> as <CODE>(1, 1, ... , 1)</CODE>. The elements of <CODE>count</CODE> correspond, in order, to the variable's dimensions. Hence, if the variable is a record variable, the first element of <CODE>count</CODE> corresponds to a count of the number of records to read. <TR>
<TD><CODE>stride</CODE><TD>A vector of ptrdiff_t integers specifying, for each dimension, the interval between selected indices. The elements of the stride vector correspond, in order, to the variable's dimensions. A value of 1 accesses adjacent values of the netCDF variable in the corresponding dimension; a value of 2 accesses every other value of the netCDF variable in the corresponding dimension; and so on. A <CODE>NULL</CODE> stride argument is treated as <CODE>(1, 1, ... , 1)</CODE>. <TR>
<TD><CODE>imap</CODE><TD>A vector of integers that specifies the mapping between the dimensions of a netCDF variable and the in-memory structure of the internal data array. imap[0] gives the distance between elements of the internal array corresponding to the most slowly varying dimension of the netCDF variable. imap[n-1] (where n is the rank of the netCDF variable) gives the distance between elements of the internal array corresponding to the most rapidly varying dimension of the netCDF variable. Intervening imap elements correspond to other dimensions of the netCDF variable in the obvious way. Distances between elements are specified in type-independent units of elements (the distance between internal elements that occupy adjacent memory locations is 1 and not the element's byte-length as in netCDF 2).<TR>
<TD><CODE>tp, up, cp, sp, ip, lp, fp, </CODE>or<CODE>, dp</CODE><TD>Pointer to the location used for computing where the data values are read; the data should be of the type appropriate for the function called. If the type of data value differs from the netCDF variable type, type conversion will occur. <A HREF=guidec-8.html#MARKER-9-1913>See Section 3.3 "Type Conversion," page 20</A>, for details.</TABLE>
</PRE>
Errors <A NAME=MARKER-10-2723></A><P>
<CODE>nc_get_varm_<B>type</B></CODE> <A NAME=MARKER-10-2724></A>returns the value <CODE>NC_NOERR <A NAME=MARKER-10-2725></A></CODE>if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>The specified <CODE>start</CODE>,<A NAME=MARKER-10-2726></A> <CODE>count</CODE>,<A NAME=MARKER-10-2727></A> and <CODE>stride</CODE> <A NAME=MARKER-10-2728></A>generate an index which is out of range. Note that no error checking is possible on the <CODE>imap</CODE> <A NAME=MARKER-10-2729></A>vector.<P>
<LI>One or more of the values are out of the range of values representable by the desired type.<P>
<LI>The specified netCDF is in define mode rather than data mode.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-643></A>
<H4>Example </H4>
The following <CODE>imap</CODE> <A NAME=MARKER-10-2730></A>vector maps in the trivial way a 4x3x2 <A NAME=MARKER-10-2731></A>netCDF variable and an internal array of the same shape: <P>
<PRE>
float a[4][3][2]; /* same shape as netCDF variable */
size_t imap[3] = {6, 2, 1};
/* netCDF dimension inter-element distance */
/* ---------------- ---------------------- */
/* most rapidly varying 1 */
/* intermediate 2 (=imap[2]*2) */
/* most slowly varying 6 (=imap[1]*3) */
</PRE>
<A NAME=MARKER-10-2732></A>Using the <CODE>imap</CODE> <A NAME=MARKER-10-2733></A>vector above with <CODE>nc_get_varm_float</CODE> <A NAME=MARKER-10-2734></A>obtains the same result as simply using <CODE>nc_get_var_float</CODE>.<A NAME=MARKER-10-2735></A><P>
Here is an example of using <CODE>nc_get_varm_float</CODE> <A NAME=MARKER-10-2736></A>to transpose a netCDF variable named <CODE>rh</CODE> which is described by the C <A NAME=MARKER-10-2737></A>declaration <CODE>float rh[6][4]</CODE> <A NAME=MARKER-10-2738></A>(note the size and order of the dimensions):<P>
<PRE>
#include <netcdf.h>
...
#define NDIM 2 /* rank of netCDF variable */
int ncid; /* netCDF ID */
int status; /* error status */
int rhid; /* variable ID */
static size_t start[NDIM] /* netCDF variable start point: */
= {0, 0}; /* first element */
static size_t count[NDIM] /* size of internal array: entire netCDF */
= {6, 4}; /* variable; order corresponds to netCDF */
/* variable -- not internal array */
static ptrdiff_t stride[NDIM] /* variable subsampling intervals: */
= {1, 1}; /* sample every netCDF element */
static ptrdiff_t imap[NDIM] /* internal array inter-element distances; */
= {1, 6}; /* would be {4, 1} if not transposing */
float rh[4][6]; /* note transposition of netCDF variable */
/* dimensions */
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid(ncid, "rh", &rhid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_get_varm_float(ncid, rhid, start, count, stride, imap, rh);
if (status != NC_NOERR) handle_error(status);
</PRE>
<A NAME=MARKER-10-2739></A>Here is another example of using <CODE>nc_get_varm_float</CODE> <A NAME=MARKER-10-2740></A>to simultaneously transpose and subsample the same netCDF variable, by accessing every other point of the netCDF variable:<P>
<PRE>
#include <netcdf.h>
...
#define NDIM 2 /* rank of netCDF variable */
int ncid; /* netCDF ID */
int status; /* error status */
int rhid; /* variable ID */
static size_t start[NDIM] /* netCDF variable start point: */
= {0, 0}; /* first element */
static size_t count[NDIM] /* size of internal array: entire */
= {3, 2}; /* (subsampled) netCDF variable; order of */
/* dimensions corresponds to netCDF */
/* variable -- not internal array */
static ptrdiff_t stride[NDIM]/* variable subsampling intervals: */
= {2, 2}; /* sample every other netCDF element */
static ptrdiff_t imap[NDIM] /* internal array inter-element distances; */
= {1, 3}; /* would be {2, 1} if not transposing */
float rh[2][3]; /* note transposition of (subsampled) */
/* netCDF variable dimensions */
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_inq_varid(ncid, "rh", &rhid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_get_varm_float(ncid, rhid, start, count, stride, imap, rh);
if (status != NC_NOERR) handle_error(status);
</PRE>
<A NAME=HEADING12-708></A>
<H2>7.15 <A NAME=MARKER-10-2741></A>Reading and Writing Character String Values</H2>
<HR>
<A NAME=MARKER-2-2742></A><A NAME=MARKER-2-2743></A><A NAME=MARKER-2-2745></A><A NAME=MARKER-2-2746></A>Character <A NAME=MARKER-2-2747></A><A NAME=MARKER-2-2748></A><A NAME=MARKER-2-2749></A><A NAME=MARKER-2-2750></A><A NAME=MARKER-2-2751></A>strings <A NAME=MARKER-2-2753></A><A NAME=MARKER-2-2757></A>are not a <A NAME=MARKER-2-2759></A><A NAME=MARKER-2-2760></A><A NAME=MARKER-2-2761></A><A NAME=MARKER-2-2762></A><A NAME=MARKER-2-2763></A><A NAME=MARKER-2-2764></A><A NAME=MARKER-2-2765></A><A NAME=MARKER-2-2766></A><A NAME=MARKER-2-2767></A><A NAME=MARKER-2-2768></A>primitive netCDF external data type, in part because FORTRAN does not support the abstraction of variable-length character strings (the FORTRAN <CODE>LEN</CODE> function returns the static length of a character string, not its dynamic length). As a result, a character string cannot be written or read as a single object in the netCDF interface. Instead, a character string must be treated as an array of characters, and array access must be used to read and write character strings as variable data in netCDF datasets. Furthermore, variable-length strings are not supported by the netCDF interface except by convention; for example, you may treat a zero byte as terminating a character string, but you must explicitly specify the length of strings to be read from and written to netCDF variables. <P>
<A NAME=MARKER-2-2771></A><A NAME=MARKER-2-2772></A>Character strings as attribute values are easier to use, since the strings are treated as a single unit for access. However, the value of a character-string attribute is still an array of characters with an explicit length that must be specified when the attribute is defined. <P>
<A NAME=MARKER-2-2776></A><A NAME=MARKER-2-2777></A>When you define a variable that will have character-string values, use a <I>character-position dimension</I> as the most quickly varying dimension for the variable (the last <A NAME=MARKER-10-2778></A>dimension for the variable in C)<A NAME=MARKER-10-2779></A>. The length of the character-position dimension will be the maximum string length of any value to be stored in the character-string variable. Space for maximum-length strings will be allocated in the disk representation of character-string variables whether you use the space or not. If two or more variables have the same maximum length, the same character-position dimension may be used in defining the variable shapes. <P>
To write a character-string value into a character-string variable, use either entire variable access or array access. The latter requires that you specify both a corner and a vector of edge lengths. The character-position dimension at the corner should be zero <A NAME=MARKER-10-2780></A>for C.<A NAME=MARKER-10-2781></A> If the length of the string to be written is <CODE>n</CODE>, then the vector of edge lengths will specify <CODE>n</CODE> in the character-position dimension, and one for all the other dimensions:<CODE>(1, 1, ... , 1, n).<A NAME=MARKER-10-2782></A></CODE><P>
<A NAME=MARKER-2-2783></A><A NAME=MARKER-2-2787></A><A NAME=MARKER-2-2788></A><A NAME=MARKER-2-2790></A><A NAME=MARKER-2-2791></A>In C, fixed-length strings may be written to a netCDF dataset without the terminating zero byte, to save space. Variable-length strings should be written <I>with</I> a terminating zero byte so that the intended length of the string can be determined when it is later read. <P>
Here is an example that defines a record variable, <CODE>tx</CODE>, for character strings and stores a character-string value into the third record using <CODE>nc_put_vara_text</CODE>. In this example, we assume the string variable and data are to be added to an existing netCDF dataset named <CODE>foo.nc</CODE> that already has an unlimited record dimension <CODE>time</CODE>. <P>
<PRE>
#include <netcdf.h>
...
int ncid; /* netCDF ID */
int chid; /* dimension ID for char positions */
int timeid; /* dimension ID for record dimension */
int tx_id; /* variable ID */
#define TDIMS 2 /* rank of tx variable */
int tx_dims[TDIMS]; /* variable shape */
size_t tx_start[TDIMS];
size_t tx_count[TDIMS];
static char tx_val[] =
"example string"; /* string to be put */
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
status = nc_redef(ncid); /* enter define mode */
if (status != NC_NOERR) handle_error(status);
...
/* define character-position dimension for strings of max length 40 */
status = nc_def_dim(ncid, "chid", 40L, &chid);
if (status != NC_NOERR) handle_error(status);
...
/* define a character-string variable */
tx_dims[0] = timeid;
tx_dims[1] = chid; /* character-position dimension last */
status = nc_def_var (ncid, "tx", NC_CHAR, TDIMS, tx_dims, &tx_id);
if (status != NC_NOERR) handle_error(status);
...
status = nc_enddef(ncid); /* leave define mode */
if (status != NC_NOERR) handle_error(status);
...
/* write tx_val into tx netCDF variable in record 3 */
tx_start[0] = 3; /* record number to write */
tx_start[1] = 0; /* start at beginning of variable */
tx_count[0] = 1; /* only write one record */
tx_count[1] = strlen(tx_val) + 1; /* number of chars to write */
status = <A NAME=MARKER-2-2792></A>nc_put_vara_text(ncid, tx_id, tx_start, tx_count, tx_val);
if (status != NC_NOERR) handle_error(status);
</PRE>
<A NAME=HEADING12-753></A>
<H2>7.16 <A NAME=MARKER-10-2793></A><A NAME=MARKER-9-2794></A>Fill Values</H2>
<HR>
<A NAME=MARKER-2-2797></A><A NAME=MARKER-2-2798></A>What happens when you try to read a value that was never written in an open netCDF dataset? You might expect that this should always be an error, and that you should get an error message or an error status returned. You <I>do</I> get an error if you try to read data from a netCDF dataset that is not open for reading, if the variable ID is invalid for the specified netCDF dataset, or if the specified indices are not properly within the range defined by the dimension lengths of the specified variable. Otherwise, reading a value that was not written returns a special <I>fill value</I> used to fill in any undefined values when a netCDF variable is first written. <P>
You may ignore fill values and use the entire range of a netCDF external data type, but in this case you should make sure you write all data values before reading them. If you know you will be writing all the data before reading it, you can specify that no prefilling of variables with fill values will occur by calling <CODE><A NAME=MARKER-2-2799></A>nc_set_fill<A NAME=MARKER-10-2800></A></CODE>before writing. This may provide a significant performance gain for netCDF writes. <P>
The variable attribute <CODE>_FillValue</CODE> may be used to specify the fill value for a variable. Their are <A NAME=MARKER-2-2801></A><A NAME=MARKER-2-2802></A><A NAME=MARKER-2-2803></A>default fill values for each type, defined in the include file <CODE>netcdf.h:<A NAME=MARKER-10-2804></A></CODE> <CODE><A NAME=MARKER-2-2805></A>NC_FILL_CHAR</CODE>, <CODE><A NAME=MARKER-2-2806></A>NC_FILL_BYTE</CODE>, <CODE><A NAME=MARKER-2-2807></A>NC_FILL_SHORT</CODE>, <CODE><A NAME=MARKER-2-2808></A>NC_FILL_INT</CODE>, <CODE><A NAME=MARKER-2-2809></A>NC_FILL_FLOAT</CODE>, and <CODE><A NAME=MARKER-2-2810></A>NC_FILL_DOUBLE</CODE>.<A NAME=MARKER-10-2811></A><P>
<A NAME=MARKER-2-2812></A><A NAME=MARKER-2-2814></A>The netCDF byte and character types have different default fill values. The default fill value for characters is the zero byte, a useful value for detecting the end of variable-length C character strings. If you need a fill value for a byte variable, it is recommended that you explicitly define an appropriate <CODE>_FillValue</CODE> attribute, as generic utilities such as <CODE>ncdump</CODE> will not assume a default fill value for byte variables.<P>
Type conversion for fill values is identical to type conversion for other values: attempting to convert a value from one type to another type that can't represent the value results in a range error. Such errors may occur on writing or reading values from a larger type (such as double) to a smaller type (such as float), if the fill value for the larger type cannot be represented in the smaller type.<P>
<A NAME=HEADING12-759></A>
<H2>7.17 Rename a Variable: <CODE><A NAME=MARKER-2-2815></A>nc_rename_var</CODE> <A NAME=MARKER-10-2816></A><CODE></CODE></H2>
<HR>
The function <CODE>nc_rename_var</CODE> <A NAME=MARKER-10-2817></A><A NAME=MARKER-2-2818></A><A NAME=MARKER-2-2819></A>changes the name of a netCDF variable in an open netCDF dataset. If the new name is longer than the old name, the netCDF dataset must be in define mode. You cannot rename a variable to have the name of any existing variable. <P>
<A NAME=HEADING12-761></A>
<H4>Usage </H4>
<PRE>
int nc_rename_var(int ncid, int varid, const char* name);
<TABLE BORDER="1"><TD><CODE>ncid</CODE><TD>NetCDF ID, from a previous call to <CODE>nc_open</CODE> or <CODE>nc_create</CODE>.<TR>
<TD><CODE>varid</CODE><TD>Variable ID.<TR>
<TD><CODE>name</CODE><TD>New name for the specified variable.</TABLE>
</PRE>
Errors <A NAME=MARKER-10-2820></A><P>
<CODE>nc_rename_var</CODE> <A NAME=MARKER-10-2821></A>returns the value <CODE>NC_NOERR <A NAME=MARKER-10-2822></A></CODE>if no errors occurred. Otherwise, the returned status indicates an error. Possible causes of errors include:<P>
<UL>
<LI>The new name is in use as the name of another variable.<P>
<LI>The variable ID is invalid for the specified netCDF dataset.<P>
<LI>The specified netCDF ID does not refer to an open netCDF dataset.<P>
</UL>
<A NAME=HEADING12-768></A>
<H4>Example </H4>
Here is an example using <CODE><A NAME=MARKER-2-2823></A>nc_rename_var</CODE> <A NAME=MARKER-10-2824></A>to rename the variable <CODE>rh</CODE> to <CODE>rel_hum</CODE> in an existing netCDF dataset named <CODE>foo.nc</CODE>: <P>
<PRE>
#include <netcdf.h>
...
int status; /* error status */
int ncid; /* netCDF ID */
int rh_id; /* variable ID */
...
status = nc_open("foo.nc", NC_WRITE, &ncid);
if (status != NC_NOERR) handle_error(status);
...
status = nc_redef(ncid); /* put in define mode to rename variable */
if (status != NC_NOERR) handle_error(status);
status = nc_inq_varid (ncid, "rh", &rh_id);
if (status != NC_NOERR) handle_error(status);
status = nc_rename_var (ncid, rh_id, "rel_hum");
if (status != NC_NOERR) handle_error(status);
status = nc_enddef(ncid); /* leave define mode */
if (status != NC_NOERR) handle_error(status);
</PRE>
<!-- TOC --><DL>
<DT><A HREF="guidec-12.html#HEADING12-17"><B>7.1 </B> - Language Types Corresponding to netCDF external data types</A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-22"><B>7.2 </B> - Create a Variable: nc_def_var </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-24"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-36"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-63"><B>7.3 </B> - Get a Variable ID from Its Name: nc_inq_varid </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-65"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-71"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-82"><B>7.4 </B> - Get Information about a Variable from Its ID: nc_inq_var family</A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-86"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-97"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-117"><B>7.5 </B> - Write a Single Data Value: nc_put_var1_type </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-119"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-142"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-160"><B>7.6 </B> - Write an Entire Variable: nc_put_var_type</A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-162"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-178"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-202"><B>7.7 </B> - Write an Array of Values: nc_put_vara_type </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-204"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-231"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-257"><B>7.8 </B> - Write a Subsampled Array of Values: nc_put_vars_type </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-259"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-291"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-316"><B>7.9 </B> - Write a Mapped Array of Values: nc_put_varm_type </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-318"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-351"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-416"><B>7.10 </B> - Read a Single Data Value: nc_get_var1_type </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-418"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-442"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-460"><B>7.11 </B> - Read an Entire Variable nc_get_var_type </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-462"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-477"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-499"><B>7.12 </B> - Read an Array of Values: nc_get_vara_type </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-501"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-526"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-549"><B>7.13 </B> - Read a Subsampled Array of Values: nc_get_vars_type </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-551"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-583"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-609"><B>7.14 </B> - Read a Mapped Array of Values: nc_get_varm_type </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-611"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-643"><B>Example</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-708"><B>7.15 </B> - Reading and Writing Character String Values</A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-753"><B>7.16 </B> - Fill Values</A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-759"><B>7.17 </B> - Rename a Variable: nc_rename_var </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-761"><B>Usage</B> - </A>
<DD>
<DT><A HREF="guidec-12.html#HEADING12-768"><B>Example</B> - </A>
<DD>
</DL>
<HR>
<ADDRESS>NetCDF User's Guide for C - 5 JUN 1997</ADDRESS>
<A HREF="guidec-13.html">[Next] </A><A HREF="guidec-11.html">[Previous] </A><A HREF="guidec-1.html">[Top] </A><A HREF="guidec-3.html">[Contents] </A><A HREF="guidec-21.html">[Index] </A><A HREF="http://www.unidata.ucar.edu/packages/netcdf/">[netCDF Home Page]</A><A HREF="http://www.unidata.ucar.edu/">[Unidata Home Page]</A><P>
</BODY>
|
