« back to all changes in this revision
Viewing changes to doc/man/ncatted.1
- browse files at revision 2
- compare with another revision
- download diff
- download tarball
- view history from revision 2
- Committer: Bazaar Package Importer
- Author(s): Brian Mays
- Date: 2002-02-07 05:42:36 UTC
- Revision ID: james.westby@ubuntu.com-20020207054236-wgx5jyzn304fiqkb
Tags: 2.2.0-1
New upstream version.
- files added:
- bld/linux1
- debian
- doc/man
- files modified:
- bld/Makefile
added
removed
doc/man/ncatted.1
1
.TH NCATTED 1
2
.SH NAME
3
ncatted \- netCDF Attribute Editor
4
.SH SYNTAX
5
ncatted [-a
6
.IR att_dsc ]
7
[-a ...] [-D] [-h]
8
[-l path] [-O] [-p path] [-R] [-r]
9
.I input-file
10
[
11
.IR output-file ]
12
.SH DESCRIPTION
13
.PP
14
.B ncatted
15
edits attributes in a netCDF file.
16
If you are editing attributes then you are spending too much time in the
17
world of metadata, and
18
.B ncatted
19
was written to get you back out as
20
quickly and painlessly as possible.
21
.B ncatted
22
can
23
.IR append ,
24
.IR create ,
25
.IR delete ,
26
.IR modify ,
27
and
28
.I overwrite
29
attributes (all explained below).
30
Furthermore,
31
.B ncatted
32
allows each editing operation to be applied
33
to every variable in a file, thus saving you time when you want to
34
change attribute conventions throughout a file.
35
.B ncatted
36
interprets character attributes as strings.
37
.PP
38
Because repeated use of
39
.B ncatted
40
can considerably increase the size
41
of the
42
.B history
43
global attribute, the
44
.B -h
45
switch is provided to override automatically appending the
46
command to the
47
.B history
48
global attribute in the
49
.IR output-file .
50
.PP
51
When
52
.B ncatted
53
is used to change the
54
.B missing_value
55
attribute,
56
it changes the associated missing data self-consistently.
57
If the internal floating point representation of a missing value,
58
e.g., 1.0e36, differs between two machines then netCDF files produced
59
on those machines will have incompatible missing values.
60
This allows
61
.B ncatted
62
to change the missing values in files from
63
different machines to a single value so that the files may then be
64
concatenated together, e.g., by
65
.BR ncrcat ,
66
without losing any
67
information.
68
.PP
69
The key to mastering
70
.B ncatted
71
is understanding the meaning of the
72
structure describing the attribute modification,
73
.IR att_dsc .
74
Each
75
.I att_dsc
76
contains five elements, which makes using
77
.B ncatted
78
somewhat complicated, but powerful.
79
The
80
.I att_dsc
81
argument structure contains five arguments in the
82
following order:
83
.PP
84
.I att_dsc
85
=
86
.IR att_nm ,
87
.IR var_nm ,
88
.IR mode ,
89
.IR att_type ,
90
.IR att_val
91
.PP
92
.TP
93
.B att_nm
94
Attribute name.
95
Example:
96
.B units
97
.TP
98
.B var_nm
99
Variable name.
100
Example:
101
.B pressure
102
.TP
103
.B mode
104
Edit mode abbreviation.
105
Example:
106
.BR a .
107
See below for complete listing of valid values of
108
.IR mode .
109
.TP
110
.B att_type
111
Attribute type abbreviation. Example:
112
.BR c .
113
See below for complete listing of valid values of
114
.IR att_type .
115
.TP
116
.B att_val
117
Attribute value. Example:
118
.BR pascal .
119
There should be no empty space between these five consecutive
120
arguments.
121
The description of these arguments follows in their order of
122
appearance.
123
.PP
124
The value of
125
.I att_nm
126
is the name of the attribute you want to edit.
127
This meaning of this should be clear to all users of the
128
.B ncatted
129
operator.
130
.PP
131
The value of
132
.I var_nm
133
is the name of the variable containing the
134
attribute (named
135
.IR att_nm )
136
that you want to edit.
137
There are two very important and useful exceptions to this rule.
138
The value of
139
.I var_nm
140
can also be used to direct
141
.B ncatted
142
to
143
edit global attributes, or to repeat the editing operation for every
144
variable in a file.
145
A value of
146
.I var_nm
147
of global\(rq indicates that
148
.I att_nm
149
refers
150
to a global attribute, rather than a particular variable's attribute.
151
This is the method
152
.B ncatted
153
supports for editing global
154
attributes.
155
If
156
.I var_nm
157
is left blank, on the other hand, then
158
.B ncatted
159
attempts to perform the editing operation on every variable in the file.
160
This option may be convenient to use if you decide to change the
161
conventions you use for describing the data.
162
.PP
163
The value of
164
.I mode
165
is a single character abbreviation (
166
.BR a ,
167
.BR c ,
168
.BR d ,
169
.BR m ,
170
or
171
.BR o )
172
standing for one of
173
five editing modes:
174
.TP
175
.B a
176
.IR Append .
177
Append value
178
.I att_val
179
to current
180
.I var_nm
181
attribute
182
.I att_nm
183
value
184
.IR att_val ,
185
if any.
186
If
187
.I var_nm
188
does not have an attribute
189
.IR att_nm ,
190
there is no
191
effect.
192
.TP
193
.B c
194
.IR Create .
195
Create variable
196
.I var_nm
197
attribute
198
.I att_nm
199
with
200
.I "att_val"
201
if
202
.I att_nm
203
does not yet exist.
204
If
205
.I var_nm
206
already has an attribute
207
.IR att_nm ,
208
there is no
209
effect.
210
.TP
211
.B d
212
.IR Delete .
213
Delete current
214
.I var_nm
215
attribute
216
.IR att_nm .
217
If
218
.I var_nm
219
does not have an attribute
220
.IR att_nm ,
221
there is no
222
effect.
223
When
224
.I Delete
225
mode is selected, the
226
.I att_type
227
and
228
.I "att_val"
229
arguments are superfluous and may be left blank.
230
.TP
231
.B m
232
.IR Modify .
233
Change value of current
234
.I var_nm
235
attribute
236
.I att_nm
237
to value
238
.IR att_val .
239
If
240
.I var_nm
241
does not have an attribute
242
.IR att_nm ,
243
there is no
244
effect.
245
.TP
246
.B o
247
.IR Overwrite .
248
Write attribute
249
.I att_nm
250
with value
251
.I att_val
252
to variable
253
.IR var_nm ,
254
overwriting existing attribute
255
.IR att_nm ,
256
if any.
257
This is the default mode.
258
.PP
259
The value of
260
.I att_type
261
is a single character abbreviation (
262
.BR f ,
263
.BR d ,
264
.BR l ,
265
.BR s ,
266
.BR c ,
267
or
268
.BR b )
269
standing for one of
270
the six primitive netCDF data types:
271
.TP
272
.B f
273
.IR Float .
274
Value(s) specified in
275
.I att_val
276
will be stored as netCDF intrinsic
277
type NC_FLOAT.
278
.TP
279
.B d
280
.IR Double .
281
Value(s) specified in
282
.I att_val
283
will be stored as netCDF intrinsic
284
type NC_DOUBLE.
285
.TP
286
.B l
287
.IR Long .
288
Value(s) specified in
289
.I att_val
290
will be stored as netCDF intrinsic
291
type NC_LONG.
292
.TP
293
.B s
294
.IR Short .
295
Value(s) specified in
296
.I att_val
297
will be stored as netCDF intrinsic
298
type NC_SHORT.
299
.TP
300
.B c
301
.I Char.
302
Value(s) specified in
303
.I att_val
304
will be stored as netCDF intrinsic
305
type NC_CHAR.
306
.TP
307
.B b
308
.IR Byte .
309
Value(s) specified in
310
.I att_val
311
will be stored as netCDF intrinsic
312
type NC_BYTE.
313
The specification of
314
.I att_type
315
is optional in
316
.I Delete
317
mode.
318
.PP
319
The value of
320
.I att_val
321
is what you want to change attribute
322
.I att_nm
323
to contain.
324
The specification of
325
.I att_val
326
is optional in
327
.I Delete
328
mode.
329
Attribute values for all types besides NC_CHAR must have an attribute
330
length of at least one.
331
Thus
332
.I att_val
333
may be a single value or one-dimensional array of
334
elements of type
335
.BR att_type .
336
If the
337
.I att_val
338
is not set or is set to empty space,
339
and the
340
.I att_type
341
is NC_CHAR, e.g.,
342
.B "-a units,T,o,c,"""""
343
or
344
.BR "-a units,T,o,c," ,
345
then the corresponding attribute is set to
346
have zero length.
347
When specifying an array of values, it is safest to enclose
348
.I att_val
349
in double or single quotes, e.g.,
350
.B "-a levels,T,o,s,""1,2,3,4"""
351
or
352
.BR "-a levels,T,o,s,'1,2,3,4'" .
353
The quotes are strictly unnecessary around
354
.I att_val
355
except
356
when
357
.I att_val
358
contains characters which would confuse the calling
359
shell, such as spaces, commas, and wildcard characters.
360
.PP
361
NCO processing of NC_CHAR attributes is a bit like Perl in that
362
it attempts to do what you want by default (but this sometimes causes
363
unexpected results if you want unusual data storage).
364
If the
365
.I att_type
366
is NC_CHAR then the argument is interpreted as a
367
string and it may contain C-language escape sequences,
368
which NCO will interpret before writing anything to disk.
369
NCO translates valid escape sequences and stores the
370
appropriate ASCII code instead.
371
Since two byte escape sequences
372
represent one byte
373
ASCII codes, e.g., ASCII 10 (decimal), the stored
374
string attribute is one byte shorter than the input string length for
375
each embedded escape sequence.
376
These sequences in particular allow convenient editing of formatted text
377
attributes.
378
See ncks netCDF Kitchen Sink, for more examples of string formatting
379
(with the
380
.B ncks
381
.B -s
382
option) with special characters.
383
.PP
384
Analogous to
385
.BR printf ,
386
other special characters are also allowed by
387
.B ncatted
388
if they are "protected" by a backslash.
389
NCO simply strips away the leading backslash from these characters
390
before editing the attribute.
391
No other characters require protection by a backslash.
392
Backslashes which precede any other character
393
will not be filtered and will be included in the attribute.
394
.PP
395
Note that the NUL character
396
which terminates C language
397
strings is assumed and need not be explicitly specified.
398
If
399
NUL
400
is input, it will not be translated (because it would
401
terminate the string in an additional location).
402
Because of these context-sensitive rules, if wish to use an attribute of
403
type NC_CHAR to store data, rather than text strings, you should use
404
.B ncatted
405
with care.
406
.PP
407
.SH EXAMPLES
408
.PP
409
Append the string "Data version 2.0.\\n" to the global attribute
410
.BR history :
411
.RS
412
ncatted -O -a history,global,a,c,"Data version 2.0\\n" in.nc
413
.RE
414
Note the use of embedded C language
415
.BR printf() -style
416
escape
417
sequences.
418
.PP
419
Change the value of the
420
.B long_name
421
attribute for variable
422
.B T
423
from whatever it currently is to "temperature":
424
.RS
425
ncatted -O -a long_name,T,o,c,temperature in.nc
426
.RE
427
.PP
428
Delete all existing
429
.B units
430
attributes:
431
.RS
432
ncatted -O -a units,,d,, in.nc
433
.RE
434
The value of
435
.I var_nm
436
was left blank in order to select all
437
variables in the file.
438
The values of
439
.I att_type
440
and
441
.I att_val
442
were left blank because
443
they are superfluous in
444
.I Delete
445
mode.
446
.PP
447
Modify all existing
448
.B units
449
attributes to "meter second-1"
450
.RS
451
ncatted -O -a units,,m,c,"meter second-1" in.nc
452
.RE
453
.PP
454
Overwrite the
455
.B quanta
456
attribute of variable
457
.B energy
458
to an array of four integers.
459
.RS
460
ncatted -O -a quanta,energy,o,s,"010,101,111,121" in.nc
461
.RE
462
.PP
463
Demonstrate input of C-language escape sequences
464
and
465
other special characters
466
.RS
467
ncatted -h -a special,global,o,c,
468
'\\nDouble quote: \\"\\nTwo consecutive double quotes: \\"\\"\\n
469
Single quote: Beyond my shell abilities!\\nBackslash: \\\\n
470
Two consecutive backslashes: \\\\\\nQuestion mark: \\?\\n' in.nc
471
.RE
472
Note that the entire attribute is protected from the shell by single
473
quotes.
474
These outer single quotes are necessary for interactive use, but may be
475
omitted in batch scripts.
Loggerhead is a web-based interface for Breezy
Version: 2.0.1