From 920393b8910a8d3fec6cd50b251c187f6b3c14e2 Mon Sep 17 00:00:00 2001 From: Russ Rew Date: Thu, 25 Apr 2013 20:50:59 +0000 Subject: [PATCH] Update nccopy documentation for -v and -g options --- ncdump/nccopy.1 | 46 ++++++++++++++++++++- ncdump/nccopy.c | 108 ++++++++++++++++++++++++------------------------ 2 files changed, 98 insertions(+), 56 deletions(-) diff --git a/ncdump/nccopy.1 b/ncdump/nccopy.1 index d36abed28d..a09e41962d 100644 --- a/ncdump/nccopy.1 +++ b/ncdump/nccopy.1 @@ -11,9 +11,11 @@ nccopy \%[-k \fI kind \fP] \%[-d \fI n \fP] \%[-s] +\%[-c \fI chunkspec \fP] \%[-u] \%[-w] -\%[-c \fI chunkspec \fP] +\%[-[v|V] var1,...] +\%[-[g|G] grp1,...] \%[-m \fI bufsize \fP] \%[-h \fI chunk_cache \fP] \%[-e \fI cache_elems \fP] @@ -133,6 +135,44 @@ also share the chunk size associated with that dimension, but the programming interface has no such restriction. If you need to customize chunking for variables independently, you will need to use the library API in a custom utility program. +.IP "\fB -v \fP \fI var1,... \fP" +The output will include data values for the specified variables, in +addition to the declarations of all dimensions, variables, and +attributes. One or more variables must be specified by name in the +comma-delimited list following this option. The list must be a single +argument to the command, hence cannot contain unescaped blanks or +other white space characters. The named variables must be valid netCDF +variables in the input-file. A variable within a group in a netCDF-4 +file may be specified with an absolute path name, such as +'/GroupA/GroupA2/var'. Use of a relative path name such as 'var' or +'grp/var' specifies all matching variable names in the file. The +default, without this option, is to include data values for \fI all \fP variables +in the output. +.IP "\fB -V \fP \fI var1,... \fP" +The output will include the specified variables only but all dimensions and +global or group attributes. One or more variables must be specified by name in the +comma-delimited list following this option. The list must be a single argument +to the command, hence cannot contain unescaped blanks or other white space +characters. The named variables must be valid netCDF variables in the +input-file. A variable within a group in a netCDF-4 file may be specified with +an absolute path name, such as '/GroupA/GroupA2/var'. Use of a relative path +name such as 'var' or 'grp/var' specifies all matching variable names in the +file. The default, without this option, is to include \fI all \fP variables in the +output. +.IP "\fB -g \fP \fI grp1,... \fP" +The output will include data values only for the specified groups. +One or more groups must be specified by name in the comma-delimited +list following this option. The list must be a single argument to the +command. The named groups must be valid netCDF groups in the +input-file. The default, without this option, is to include data values for all +groups in the output. +.IP "\fB -G \fP \fI grp1,... \fP" +The output will include only the specified groups. +One or more groups must be specified by name in the comma-delimited +list following this option. The list must be a single argument to the +command. The named groups must be valid netCDF groups in the +input-file. The default, without this option, is to include all groups in the +output. .IP "\fB -m \fP \fI bufsize \fP" An integer or floating-point number that specifies the size, in bytes, of the copy buffer used to copy large variables. A suffix of K, M, G, @@ -160,7 +200,9 @@ cache size has been implemented yet. Using the '-w' option may provide better performance, if the output fits in memory. .IP "\fB -e \fP \fI cache_elems \fP" For netCDF-4 output, including netCDF-4 classic model, specifies -number of elements that the chunk cache can hold. This is not a +number of elements that the chunk cache can hold. A suffix of K, M, G, +or T multiplies the copy buffer size by one thousand, million, +billion, or trillion, respectively. This is not a property of the file, but merely a performance tuning parameter for avoiding compressing or decompressing the same data multiple times while copying and changing chunk shapes. The default is 1009 (or diff --git a/ncdump/nccopy.c b/ncdump/nccopy.c index 4c494138d9..d8a153457e 100644 --- a/ncdump/nccopy.c +++ b/ncdump/nccopy.c @@ -1535,8 +1535,9 @@ usage(void) @section SYNOPSIS \code -nccopy [-k kind] [-d n] [-s] [-u] [-w] [-c chunkspec] [-m bufsize] - [-h chunk_cache] [-e cache_elems] [-r] infile outfile +nccopy [-k kind] [-d n] [-s] [-c chunkspec] [-u] [-w] [-[v|V] var1,...] + [-[g|G] grp1,...] [-m bufsize] [-h chunk_cache] [-e cache_elems] + [-r] infile outfile \endcode @section DESCRIPTION @@ -1657,6 +1658,56 @@ programming interface has no such restriction. If you need to customize chunking for variables independently, you will need to use the library API in a custom utility program. +@par -v \a var1,... + +@par +The output will include data values for the specified variables, in +addition to the declarations of all dimensions, variables, and +attributes. One or more variables must be specified by name in the +comma-delimited list following this option. The list must be a single +argument to the command, hence cannot contain unescaped blanks or +other white space characters. The named variables must be valid netCDF +variables in the input-file. A variable within a group in a netCDF-4 +file may be specified with an absolute path name, such as +`/GroupA/GroupA2/var'. Use of a relative path name such as `var' or +`grp/var' specifies all matching variable names in the file. The +default, without this option, is to include data values for \e all variables +in the output. + +@par -V \a var1,... + +@par +The output will include the specified variables only but all dimensions and +global or group attributes. One or more variables must be specified by name in the +comma-delimited list following this option. The list must be a single argument +to the command, hence cannot contain unescaped blanks or other white space +characters. The named variables must be valid netCDF variables in the +input-file. A variable within a group in a netCDF-4 file may be specified with +an absolute path name, such as `/GroupA/GroupA2/var'. Use of a relative path +name such as `var' or `grp/var' specifies all matching variable names in the +file. The default, without this option, is to include \e all variables in the +output. + +@par -g \e grp1,... + +@par +The output will include data values only for the specified groups. +One or more groups must be specified by name in the comma-delimited +list following this option. The list must be a single argument to the +command. The named groups must be valid netCDF groups in the +input-file. The default, without this option, is to include data values for all +groups in the output. + +@par -G \e grp1,... + +@par +The output will include only the specified groups. +One or more groups must be specified by name in the comma-delimited +list following this option. The list must be a single argument to the +command. The named groups must be valid netCDF groups in the +input-file. The default, without this option, is to include all groups in the +output. + @par -m \e bufsize @par An integer or floating-point number that specifies the size, in bytes, @@ -1707,57 +1758,6 @@ file in memory before copying. Requires that input file be small enough to fit into memory. For \b nccopy, this doesn't seem to provide any significant speedup, so may not be a useful option. -@par -g \e grp1,... - -@par -The output will include data values only for the specified groups. -One or more groups must be specified by name in the comma-delimited -list following this option. The list must be a single argument to the -command. The named groups must be valid netCDF groups in the -input-file. The default, without this option, is to include data values for all -groups in the output. - -@par -G \e grp1,... - -@par -The output will include only the specified groups. -One or more groups must be specified by name in the comma-delimited -list following this option. The list must be a single argument to the -command. The named groups must be valid netCDF groups in the -input-file. The default, without this option, is to include all groups in the -output. - -@par -v \a var1,... - -@par -The output will include data values for the specified variables, in -addition to the declarations of all dimensions, variables, and -attributes. One or more variables must be specified by name in the -comma-delimited list following this option. The list must be a single -argument to the command, hence cannot contain unescaped blanks or -other white space characters. The named variables must be valid netCDF -variables in the input-file. A variable within a group in a netCDF-4 -file may be specified with an absolute path name, such as -`/GroupA/GroupA2/var'. Use of a relative path name such as `var' or -`grp/var' specifies all matching variable names in the file. The -default, without this optiong, is to include data values for \e all variables -in the output. - -@par -V \a var1,... - -@par -The output will include the specified variables only but all dimensions and -attributes. One or more variables must be specified by name in the -comma-delimited list following this option. The list must be a single argument -to the command, hence cannot contain unescaped blanks or other white space -characters. The named variables must be valid netCDF variables in the -input-file. A variable within a group in a netCDF-4 file may be specified with -an absolute path name, such as `/GroupA/GroupA2/var'. Use of a relative path -name such as `var' or `grp/var' specifies all matching variable names in the -file. The default, without this option, is to include \e all variables in the -output. - - @section EXAMPLES @subsection simple_copy Simple Copy @@ -1830,7 +1830,7 @@ nccopy -w -c time/1000,lat/40,lon/40 slow.nc fast.nc \endcode @section see_also SEE ALSO -netcdf(3), ncgen(1), netcdf(3) +ncdump(1), ncgen(1), netcdf(3) */ int