Since the construction of a report layout or template can be somewhat difficult to do from scratch, it is usually a good idea to run SREPORT in interactive mode first. The interactive processor will use many default options and will produce a file containing the commands and the template for the report. The default report will be adequate for many purposes. If, however, you need to refine the report layout, it will be relatively simple to edit the file produced by the interactive processor. The revised file can then be executed by SREPORT in either interactive or batch mode.
In order to check the syntax of the batch file (but not execute the commands), use the `-n' option:
sreport -b filename -n
Keyword Possible Specification Default (if no keyword)
_____________________________________________________________________
(One of the next pair must be given, to indicate the type of report.)
BREAKvar= Name of break variable REQUIRED for breakvar type
ROWvars= Name(s) of row variables REQUIRED for rowvars type
DATA= Name(s) of datafile(s) REQUIRED
DDL= Name of DDL file REQUIRED
Weight= Name of weight variable No weighting
Filter= Name(s) and codes of filter No filters
variable(s)
SAvefile= Filename to receive output Output sent to screen
(standard output)
Margin= Number of spaces for 0
left margin
PAgelength= Number of lines on a page 66
(0 = continuous output)
NMAX= Maximum number of cases to read Read all cases
(used for testing)
The only keywords that can be repeated are `rowvars=', `data=',
and `filter='. When repeated, the specifications given after the
equal sign are appended to the previously given specifications.
Multiple specifications, however, can also be given after a
single keyword by separating the file names or variable names
with blanks or commas. If there are too many specifications to
fit on one line, the keyword must be repeated.
Each of the definitions uses syntax of the form `&[character] = something', where any SINGLE upper- or lower-case character can be used after the `&'. In order to use a function of a variable, that variable must have been previously defined; notice in the example above that the mean of `age' is expressed as `mean(&a)'. Many functions can be used. A complete list is given below in the section labeled "Function Definitions."&a = age &b = education &c = mean(&a) &d = stddev(&a) &e = mean(&b)
The ROWVARS type of report does not require this series of
commands, since the variables are specified with the `rowvars='
keyword as indicated above. However, it is possible to specify
the desired statistics for the row variables in the form
`&a=MEAN' and then use the `&a' as the definition of a column, as
described in the next section. Although this two-step
specification of statistics is unnecessarily complex for
contructing a template from scratch, the interactive processor
generates templates for ROWVARS reports in this manner, because
it is easier to use the same syntax for both types of reports.
The meaning of each column is as follows:*COLUMNS &cat &clabel &c &d &e
Note in particular the special meaning of `&cat' and `&clabel' (these can be in upper or lower case, and `clabel' can be abbreviated to `clab'). The meanings of the other symbols are defined within the command file itself. The column specification for a ROWVARS type of report is simpler. A typical example would be:&cat The category code of the break variable &clabel The label of the category code &c mean(&a) - the mean of the variable &a (age) &d stddev(&a) - the standard deviation of &a &e mean(&b) - the mean of &b (education)
The meaning of each column is as follows:*COLUMNS &name &label MEAN STDDEV NVALID
Once again, note the special meaning of `&name' and `&label'. The other column specifications are simply the names of functions; any of the arithmetic functions listed in the summary below can be used. (All of these specifications and function names can be in upper or lower case, and `label' can be abbreviated to `lab'.)&name The name of each row variable &label The long label of each row variable MEAN The mean of each row variable STDDEV The standard deviation of each row variable VALIDN The number of valid cases for each row variable
*ROWS
XXX LLLLLLLLLL X,XXX.X X,XXX.XX XX,XXX.X
This template is a "picture" of how each row of the report will
be written. The first defined column (&cat) is a number and will
be placed in the first three positions in the row. The second
defined column (&clabel) is a string of characters; it will be
left justified in the 10-position area designated by
`LLLLLLLLLL'. The third and fifth columns (means of two
variables) will be numbers printed with one decimal place; commas
will also be inserted if the number exceeds 999.9. The fourth
column (standard deviation) will be printed with two decimal
places.
The formats that can be used in row specifications are given
below. The maximum width of a field is defined by the width of
the format string. If a number is too large to fit into a field,
an error message will be generated, and the program will stop.
If a string of characters such as a variable name or label is
longer than the length of the format string, the string will be
truncated in the report, and a warning message will be displayed.
Since a template can include literal text as well as formats,
each format must be clearly recognizable as such. That is to
say, each format must only contain consecutive and identical
capital letters (such as CCC, LLL, RRRR, or BB); the XX numeric
format, however, can include a few other characters as shown
below. A format must be separated by blanks from other text in
the template. Text format strings must be at least two
characters long.
Numeric formats
(All can include decimal points; numbers are rounded to fit.)
XXXXXX Whole number, no decimal points
XXX.XX Number of decimal points specified
XX,XXX Comma(s) inserted as needed
(The comma can appear anywhere in the format)
$X,XXX Dollar sign and comma(s)
XXXXX% Percent sign put at the end of the number
(XXXX) Parentheses put around the number
(The number part of the format can be any of the above)
Text formats
CCCCCC Centered text
LLLLLL Left-justified text
RRRRRR Right-justified text
Format to suppress a field
BBBBBB Blank out the field (numeric or text)
(used to blank out a field in a row or a total)
*TOTAL
------- -------- --------
Total X,XXX.X X,XXX.XX XX,XXX.X
Notice that the first row of the template has some lines, to
indicate the bottom of each column. The next line has the word
"Total" and the same format strings as the template for the rows.
The format strings are the only required elements, and they can
be different from the formats for the other rows -- with a
different number of decimal places, for instance.
If you want some of the totals but not all, you can blank out the
ones you do not want by using a special format string `BBBBBB'
(at least two B's are necessary). For example, to print only the
first and third totals in the example above, you would use the
following command:
*TOTAL
------- -------
Total X,XXX.X BBBBBBBB X,XXX.X
*HEADER
Page &page
Comparison of Groups
Mean Std Dev Mean
Age Age Education
Group
*(next command or end of file)
The template of the header includes any blank lines up to the
next command or until the end of the command file. The text of
the header will appear as is at the top of the report, except for
the substitution of the value of `&page', which is the page
number.
A footer can also be specified in the same way as the header.
One possible footer is the following:
*FOOTER everypage
Report printed on &date
Weight variable: &weight
Filter variable: &filter
*(next command or end of file)
The substitution variables that can be included in the template
for a header or a footer are given in the following list. The
names can be given in either upper or lower case, and some names
can be abbreviated. The minimum required name is given below in
upper case; the characters in lower case are optional and are
ignored by the program. References to INDIVIDUAL variables,
however, are sensitive to case -- `&a' refers to a different
variable than `&A'.
&DATE Current date, in form: July 15, 1993
&PAGE Page number within the report
&NAME Name of the break variable
&LABel Long label of the break variable
&FILter Name of filter variable(s) and codes
&WEIght Name of the weight variable
&DATA Name of ascii data file(s) used as input
&DDL Name of DDL file
&a Name of variable referred to as `&a'
(if &a=age, the string `age' will be substituted)
If there are no actual filter or weight variables in a report,
the `&filter' and `&weight' substitution variables return blanks.
Headers and footers by default only appear once in a multi-line
report -- the header appears at the top of the first page, and
the footer appears only on the last page. If the word
`everypage' (which can be in upper or lower case and can be
abbreviated to `EV' or `ev') follows a *HEADER or *FOOTER
command, however, the corresponding header or footer is printed
on every page of a multi-page report. With the `everypage'
specification, the footer is also placed at the bottom of the
page, instead of immediately following the last row of
statistics.
Templates can include tabs, formfeeds, and other special
characters. The user should be aware, however, that the
formatting of the resulting report will be dependent on the
settings of the output device. The program will issue a warning
if such characters are used, in case they were inserted by
accident.
&say "message" Display "message" on the screen.
If no message is specified,
a blank line is produced.
&prompt Use a standard prompt to obtain data
(can be used with any keyword or
reference to a variable). For keywords
that can be repeated, it is permissible
to mix fixed specifications with the
"&prompt" function in order to allow
additional specifications at run-time.
However, the "keyword = &prompt" line must
follow any fixed specifications for that
keyword.
&ask "message" Alternative to `&prompt', if you
want to customize the prompt for the user.
Display "message," input a line of text,
and pass the input to one of the keywords.
Some examples of the usage of these interactive commands are the
following:
&say "Enter the names of the two variables to be analyzed"
&say "Possible variables include age, educ, gender, income, spend"
&say
&a = &prompt
&b = &prompt
# (The program will prompt the user for variable names, which
# will then be used in the remaining commands.)
weight = &prompt
savefile = &ask "Enter name of file on which to write results"
# (The program will prompt the user for the required names.)
filter = &prompt
&say "This report can be limited to either male or female repondents"
filter=gender( &ask"Enter `1' for males; `2' for females" )
&say "If you want to use another filter, enter the information now"
filter= &ask"Filter var:" ( &ask"Categories to include:" )
# (Filters can use the standard prompt, or you can customize the
# prompt in various ways.)
The name of each function can be given in either upper or lower case. Some function names can be abbreviated. The minimum required name is given below in upper case; the characters in lower case are optional and are ignored by the program.
In the following lists of functions the arguments given as examples have the following meaning:
The term `valid' in the following definitions means that the
value of a variable is not equal to the missing-data code
nor is it beyond the defined range of valid codes.
MEAN(&a) Mean
MAXimum(&a) Maximum valid value
MINimum(&a) Minimum valid value
STDDEV(&a) Standard deviation
STDERR(&a) Standard error
SUM(&a) Sum of a variable across cases
Nvalid(&a) Number of valid cases
VARiance(&a) Variance
WNvalid(&a) Weighted number of valid cases
WSTDERR(&a) Standard error, computed with weighted N
The functions `wnvalid' and `wstderr' generate the same
numbers as `nvalid' and `stderr' if no weight variable has
been specified.
In a ROWVARS type of report, only the function name is
given; it applies automatically to every row variable.
FREQuency(&a,c-d,e,f-g) Number of cases that fall within the
given ranges of `&a'.
BIFREQuency(&a,c-d; &b,e-f,g) Number of cases that fall within
the given ranges of BOTH variables.
NOTICE THE SEMICOLON, used to separate the
ranges of the two variables.
The character `*' used as the range of a variable refers to
all valid codes. If a weight variable has been specified,
the number of cases is weighted.
ADD(&x,&y,&z,...) Add the arguments SUBtract(&x,&y) Subtract: &x - &y MULTiply(&x,&y,&z,...) Multiply the arguments DIVide(&x,&y) Divide: &x / &y AVerage(&x,&y,&z,...) Average (mean) of the arguments GReat(&x,&y,&z,...) The greatest argument (e.g., great(2,4,6) = 6) LEast(&x,&y,&z,...) The smallest argument (e.g., least(2,4,6) = 2) SQRT(&x) Square root of argument
Note that anything on a line begining with `#' is ignored by the batch processor and can therefore be used for comments. Blank lines are ignored except within templates.
Additional examples of command files can be examined in the SREPORT example file.
Example of a command file for a BREAKVAR type of report
# General report characteristics breakvar = gender data = testdat ddl = testddl # Specification of variables &a = age &b = education &c = mean(&a) &d = stddev(&a) &e = mean(&b) # Which variables go in which column (required) *COLUMNS &cat &clabel &c &d &e # Template for each row (required) *ROWS XXX LLLLLLLLLL X,XXX.X X,XXX.XX XX,XXX.X # Template for a row of totals (optional) *TOTAL ------- -------- -------- Total X,XXX.X X,XXX.XX XX,XXX.X # Template for header - top of report (optional) *HEADER Page &page Comparison of Groups Mean Std Dev Mean Age Age Education Group # Template for footer - bottom of report (optional) *FOOTER everypage Report printed on &date Weight variable: &weight Filter variable: &filter
| sreport | Basic information about SREPORT |
| sreport examples | Examples of SREPORT command files |
| sreport functions | Summary of SREPORT functions and formats |
| DDL | Data Description Language |