dumpvar - dump variable data in ASCII

dumpvar - Dumps variable data in ASCII

SYNOPSIS

dumpvar  [ parameter=value ]  [ inputfile ... ]

Parameters are: include_vars, num_row_dims, stack_vars, dim_starts, dim_counts, list_dims, hex_output, printout

DESCRIPTION

dumpvar dumps variable data in ASCII. Unlike printvar, which outputs scaled data, dumpvar outputs unscaled data, e.g., data exactly as it is stored.

dumpvar's output report is arranged in rows. The report rows correspond to to different values (d1, d2, ..., dk) of leading dimensions D1, D2, ..., Dk. k is specified by the num_row_dims parameter. Each variable dumped must have the same leading dimensions.

The user specifies which rows to report using the dim_starts and dim_counts parameters. If num_row_dims=k, and

dim_starts=i1,...,ik and dim_counts=n1,...,nk,

then there will be n1*...*nk rows reported, starting with row (i1,...,ik) and ending with row (i1+n1-1,...,ik+nk-1).

If stack_vars=no, each report row will consist of exactly one text line. All row values for each variable will be reported on the same text line. If stack_vars=yes, each report row will consist of multiple text lines, one line per variable.

PARAMETERS

include_vars: Specifies the list of variables to dump. If the list is preceded by a minus sign, all variables except those listed will be printed. Wildcards * and ? are allowed. The default is to print all variables.

num_row_dims: Specifies the number of leading (or row) dimensions. All variables dumped must have the same leading dimensions. Valid responses are [> 0]. The default is 1.

stack_vars: Specifies how data for different variables is to be reported. If stack_vars=yes, data for different variables is dumped on different text lines. Otherwise, all variable data for each row is reported on the same text line. Valid responses are [yes, no]. The default is no.

dim_starts: Specifies 1-relative coordinates corresponding to the first row to be reported. The default is 1 for each row dimension.

dim_counts: Specifies, for each row dimension, the number of different indexes. The number of rows reported will be the product of theses indexes. The default is 1 for each row dimension.

list_dims: Specifies whether or not row dimension indexes for each output line are to be printed. Dimension indexes are 1-relative. Valid responses are [yes, no]. The default is yes.

hex_output: Specifies whether or not variable data is to be dumped in hexadecimal format, as opposed to decimal format. Valid responses are [yes, no]. The default is no.

printout: Specifies whether or not output is to be directed to the printer, as opposed to the screen. Valid responses are [yes, no]. The default is no.

EXAMPLES

The following examples are based on the trivial test dataset XX, which contains the following three variables:

xx[i,j] = i + j - 1, 1 <= i <= 4, 1 <= j <= 5
yy[i,j] = i + j + 9, 1 <= i <= 4, 1 <= j <= 5
zz[i]   = i + 20,    1 <= i <= 4

Example 1, dump all three variables, all variable data for each row on the same text line.

% dumpvar XX
include_vars   : char(255) ? [] xx yy zz
num_row_dims   : int       ? [1]
stack_vars     : char(  3) ? [no]
dim_starts     : int (  5) ? [1]
dim_counts     : int       ? [1] 4
list_dims      : char(  3) ? [yes]
hex_output     : char(  3) ? [no]
printout       : char(  3) ? [no]

Dumpvar  xx  Page 1

           xx                  yy                  zz
       1    1   2   3   4   5  11  12  13  14  15  21
       2    2   3   4   5   6  12  13  14  15  16  22
       3    3   4   5   6   7  13  14  15  16  17  23
       4    4   5   6   7   8  14  15  16  17  18  24

Example 2, dump all three variables, data for each variable row on separate text lines.

% dumpvar XX
include_vars   : char(255) ? [] xx yy zz
num_row_dims   : int       ? [1]
stack_vars     : char(  3) ? [no] y
dim_starts     : int (  5) ? [1]
dim_counts     : int       ? [1] 4
list_dims      : char(  3) ? [yes]
hex_output     : char(  3) ? [no]
printout       : char(  3) ? [no]

Dumpvar  xx  Page 1

       1    1   2   3   4   5  xx
       1   11  12  13  14  15  yy
       1   21  zz

       2    2   3   4   5   6  xx
       2   12  13  14  15  16  yy
       2   22  zz

       3    3   4   5   6   7  xx
       3   13  14  15  16  17  yy
       3   23  zz

       4    4   5   6   7   8  xx
       4   14  15  16  17  18  yy
       4   24  zz

Example 3, dump the middle three columns of variables xx and yy by making the number row dimensions equal to 2. zz cannot be included because it does not have two dimensions.

% dumpvar XX
include_vars   : char(255) ? [] xx yy
num_row_dims   : int       ? [1] 2
stack_vars     : char(  3) ? [no]
dim_starts     : int (  5) ? [1 1] 1 2
dim_counts     : int (  2) ? [1 1] 4 3
list_dims      : char(  3) ? [yes]
hex_output     : char(  3) ? [no]
printout       : char(  3) ? [no]
Dumpvar  xx  Page 1

                   xx  yy
       1       2    2  12
       1       3    3  13
       1       4    4  14
       2       1    2  12
       2       2    3  13
       2       3    4  14
       2       4    5  15
       3       1    3  13
       3       2    4  14
       3       3    5  15
       3       4    6  16
       4       1    4  14

Example 4, dump the middle three columns of variable xx and yy, but keeping the number of row dimensions equal to 1. See NOTES.

% dumpvar XX
include_vars   : char(255) ? [] xx yy
num_row_dims   : int       ? [1]
stack_vars     : char(  3) ? [no] yes
dim_starts     : int (  5) ? [1] 1 2
dim_counts     : int (  2) ? [1] 4 3
list_dims      : char(  3) ? [yes]
hex_output     : char(  3) ? [no]
printout       : char(  3) ? [no]

Dumpvar  xx  Page 1

       1    2   3   4  xx
       1   12  13  14  yy

       2    3   4   5  xx
       2   13  14  15  yy

       3    4   5   6  xx
       3   14  15  16  yy

       4    5   6   7  xx
       4   15  16  17  yy

NOTES

Ordinarily, dim_starts and dim_counts have exactly num_row_dims values. However, in the last example, dim_starts and dim_counts were assigned more than num_row_dims values. This trick allowed variables xx and yy to be subset along a dimension that was not a row dimension. If variable xx was include in the list of variables to dump, it would not have been affected, since it only had one dimension.

Output text lines are limited to 256 characters. No report will be generated if any text line will exceed 256 characters.