PRINT directive

Prints data in tabular format in an output file, unformatted file or text.

Options

CHANNEL = identifier	Channel number of file, or identifier of a text to store output; default current output file
SERIAL = string token	Whether structures are to be printed in serial order, i.e. all values of the first structure, then all of the second, and so on (yes, no); default no, i.e. values in parallel
IPRINT = string tokens	What identifier and/or text to print for the structure (identifier, extra, associatedidentifier), for a table associatedidentifier prints the identifier of the variate from which the table was formed (e.g. by TABULATE), IPRINT=* suppresses the identifier altogether; default iden
RLPRINT = string tokens	What row labels to print (labels, integers, identifiers), RLPRINT=* suppresses row labels altogether; default labe, iden
CLPRINT = string tokens	What column labels to print (labels, integers, identifiers), CLPRINT=* suppresses column labels altogether; default labe, iden
RLWIDTH = scalar	Field width for row labels; default 13
INDENTATION = scalar	Number of spaces to leave before the first character in the line; default 0
WIDTH = scalar	Last allowed position for characters in the line; default width of current output file
SQUASH = string token	Whether to omit blank lines in the layout of values (yes, no); default no
MISSING = text	What to print for missing value; default uses '*' for numbers and blanks in texts
ORIENTATION = string token	How to print vectors or pointers (down, across); default down, i.e. down the page
ACROSS = scalar or factors	Number of factors or list of factors to be printed across the page when printing tables; default for a table with two or more classifying factors prints the final factor in the classifying set and the notional factor indexing a parallel list of tables across the page, for a one-way table only the notional factor is printed across the page
DOWN = scalar or factors	Number of factors or list of factors to be printed down the page when printing tables; default is to print all other factors down the page
WAFER = scalar or factors	Number of factors or list of factors to classify the separate “wafers” (or slices) used to print the tables; default 0
PUNKNOWN = string token	When to print unknown cells of tables (present, always, zero, missing, never); default pres
UNFORMATTED = string token	Whether file is unformatted (yes, no); default no
REWIND = string token	Whether to rewind unformatted file before printing (yes, no); default no
WRAP = string token	Whether to wrap output that is too long for one line onto subsequent lines, rather than putting it into a subsequent “block” (yes, no); default no
STYLE = string token	Style to use for an output file (plaintext, formatted); default * uses the current style of the channel
PMARGIN = string tokens	Which margins to print for tables (full, columns, rows, wafers); default full
OMITMISSINGROWS = string token	Whether to omit rows of tables that contain only missing values (yes, no); default no
VSPECIAL = scalar or variate	Special values to be modified in the output
TSPECIAL = text	Strings to be used for the special values; must be set if VSPECIAL is set

Parameters

STRUCTURE = identifiers	Structures to be printed
FIELDWIDTH = scalars	Field width in which to print the values of each structure (a negative value –n prints numbers in E-format in width n); if omitted, a default is determined (for numbers, this is usually 12; for text, the width is one more character than the longest line)
DECIMALS = structures	Number of decimal places for numerical data structures, a scalar if the same number of decimals is to be used for all values of the structure, or a data structure of the same type and size to use different numbers of decimals for each value; if omitted or set to a missing value, a default is determined which prints the mean absolute value to 4 significant figures
CHARACTERS = scalars	Number of characters to print in strings
SKIP = scalars or variates	Number of spaces to leave before each value of a structure (* means a new line before structure)
FREPRESENTATION = string tokens	How to represent factor values (labels, levels, ordinals); default is to use labels if available, otherwise levels
JUSTIFICATION = string tokens	How to position values within the field (right, left, center, centre); if omitted, right is assumed
MNAME = string tokens	Name to print for table margins (margin, total, nobservd, mean, minimum, maximum, variance, count, median, quantile); if omitted, “Margin” is printed
DREPRESENTATION = scalars or texts	Format to use for dates and times (stored in numerical structures)
HEADING = texts	Heading to be used for vectors printed in columns down the page; default is to use the information requested by the IPRINT option
TLABELS = texts	If this is specified for a table STRUCTURE, the values of the table are interpreted as references to lines within the TLABELS text that are to be printed instead of the values of the table itself

Description

The contents of Genstat data structures can be displayed, with appropriate labelling, using the PRINT directive. Output can be printed in the current output channel, or sent to other channels, or put into a text structure. PRINT has many options and parameters to allow you to control the style and format of the output but, in most cases, these can be left with their default settings.

For a quick display of the contents of a list of data structures, you need only give the name of the directive, PRINT, and then list their identifiers. For example

PRINT Source,Amount,Gain

The output is fully annotated with the identifiers, and with row and column labels or numbers, where appropriate. Factors are represented by their labels if available, and otherwise by their levels. The layout of the values is determined automatically by the size and shape of the structures to be printed, and by the space needed to print individual values. The output is arranged in columns; the structures are split if the page is not wide enough, so that one set of columns is completed before the next is printed.

With vectors, the default is to print their values in parallel. Alternatively, you can request that structures are printed in series, one below another, by setting option SERIAL=yes. Of course, if the structures to be printed have different shapes or sizes, their values can be printed only in series. The setting SERIAL=no is then ignored except that, to save space, any vectors or pointers are then printed across the page (that is, as though you had set ORIENTATION=across).

Genstat annotates each set of values by the identifier of the structure (but this can be controlled by the IPRINT option or the HEADING parameter described below), and it automatically chooses a suitable format. For a numerical structure, the default is to use a field of f characters. Generally, the value of f is 12, but another value can be defined using the FIELDWIDTH option of the SET directive. If the DECIMALS parameter was set when the structure was declared, this will define the number of decimal places in the output; otherwise, the number of decimal places is determined by calculating the number that would be required to print its mean absolute value to at least d significant figures. Generally, d is four, but this can be redefined using the SIGNIFICANTFIGURES option of the SET directive. Texts (and labels of factors) are usually printed in a field of f characters but this is extended if any of the strings in the text requires a wider field. You can define your own formats using the parameters FIELDWIDTH, DECIMALS, CHARACTERS, SKIP and JUSTIFICATION.

FIELDWIDTH and DECIMALS both operate in a straightforward way. The only potential complication is that a negative FIELDWIDTH can be used to print numbers in scientific format (for example 7.3 E1 instead of 73), with DECIMALS significant places. The DECIMALS parameter is ignored for strings, like the labels of the factors Source and Amount. For a numerical data structure, you can either set DECIMALS to a scalar to use the same number of decimals for all the values of the structure. Alternatively, if you want to use a different number of decimals for each value, you can supply a data structure of the same type and size as STRUCTURE. If DECIMALS is omitted or if it contains a missing value, a default is used which prints the mean absolute value to d significant figures, as above.

In the same way, the CHARACTERS parameter is ignored for numbers; for strings, it allows you to control the number of characters that are printed. By default, Genstat prints all the characters in each string of a text or factor label, unless the CHARACTERS parameter was set to a lesser number when the text or factor was declared.

Textual strings can contain typesetting commands to represent Greek and special symbols. (These are most useful in PRINT, but can be used in any directive that generates output.) The commands are converted automatically by Genstat to match the style of output (HTML, LaTeX, plain-text or RTF). The commands are all introduced by the character tilde (~). So, to use tilde as an ordinary character, you need to specify the special symbol ~{~} as defined below.

If Genstat finds a mistake in the syntax of a command, it will not issue a failure diagnostic but will output the remainder of the string (including any commands) as plain text. So, for example, legacy code containing tilde characters should continue to generate the output in its previous form. The following comands define Greek characters and various special symbols.

~{~}	tilde symbol; also see ~{tilde}
~{alpha}	Greek character alpha
~{beta}	Greek character beta
~{gamma}	Greek character gamma
~{delta}	Greek character delta
~{epsilon}	Greek character epsilon
~{varepsilon}	Greek character epsilon (variant)
~{zeta}	Greek character zeta
~{eta}	Greek character eta
~{theta}	Greek character theta
~{vartheta}	Greek character theta (variant)
~{iota}	Greek character iota
~{kappa}	Greek character kappa
~{lambda}	Greek character lambda
~{mu}	Greek character mu
~{nu}	Greek character nu
~{xi}	Greek character xi
~{omicron}	Greek character omicron
~{pi}	Greek character pi
~{varpi}	Greek character pi (variant)
~{rho}	Greek character rho
~{varrho}	Greek character rho (variant)
~{sigma}	Greek character sigma
~{varsigma}	Greek character sigma (terminal version)
~{tau}	Greek character tau
~{upsilon}	Greek character upsilon
~{phi}	Greek character phi
~{varphi}	Greek character phi (variant)
~{chi}	Greek character chi
~{psi}	Greek character psi
~{omega}	Greek character omega
~{bull} or ~{bullet}	bullet
~{cdot}	decimal point; also see ~{middot}
~{div} or ~{divide}	divide symbol
~{gg}	“>>” symbol; also see ~{raquo}
~{laquo}	“<<” symbol; also see ~{ll}
~{ll}	“<<” symbol; also see ~{laquo}
~{middot}	alternative way of specifying a decimal point; also see ~{cdot}
~{minus}	minus symbol
~{plusminus}	“+ or minus” symbol; also see ~{pm}
~{pm}	“+ or minus” symbol; also see ~{plusminus}
~{raquo}	“>>” symbol; also see ~{gg}
~{sqrt}	square-root symbol
~{oplus}	+ within circle
~{ominus}	minus symbol within circle
~{otimes}	multiply symbol within circle
~{oslash}	slash symbol within circle
~{odot}	dot within circle
~{tilde}	tilde symbol; also see ~{~}
~{times}	multiply symbol
~{break}	starts a new line in captions

The character definitions (within the curly brackets) can be abbreviated. Genstat checks through the possibilities, in the order defined above, until it finds the first match. Greek characters in capital letters can be obtained by beginning the name of the character with a capital letter, for example ~{Sigma}; subsequent capital letters are irrelevant.

The style of font can be changed to bold or italic.

~bold or ~b	introduces a sequence of bold characters; these must be placed within curly brackets and any spaces between ~bold and the opening curly bracket are ignored.
	e.g. ~bold {Please note:}
~italic or ~i	introduces a sequence of italic characters; these must be placed within curly brackets and any spaces between ~italic and the opening curly bracket are ignored.
	e.g. ~italic {Passer domesticus}

You can also produce output in the same style as Genstat uses when it echoes commands in the output.

~genstat or ~g	introduces some output in the style that Genstat uses to echo commands; it must be placed within curly brackets and any spaces between ~genstat and the opening curly bracket are ignored.

You can define subscripts and superscripts to use, for example, in equations.

~_	introduces a subscript; if the subscript is a single character it can be placed immediately after _, otherwise it must be placed within curly brackets; any spaces between ~_ and the opening curly bracket are ignored.
~^	introduces a superscript; if the superscript is a single character it can be placed immediately after ^, otherwise it must be placed within curly brackets; any spaces between ~^ and the opening curly bracket are ignored.

You can use special characters in subscripts or superscripts, but fonts must be specified outside the subscript or superscript. For example:

~i {x~_{i,j}}	defines xi,j,
x~^ {2n}	defines x2n, and
~i{x~_{i,j}}~^2	defines xi,j2
~b{X}~i{~_{i,j}}~^2	defines Xi,j2.

For additional flexibility, you can specify output information in either HTML, LaTeX or RTF. This will be inserted only into output constructed by Genstat in the same style. You can also supply information to be included only in plain-text output (which may, for example, be your translation of the HTML, LaTeX or RTF information).

~html or ~h	introduces a sequence of information in HTML; the information must be placed within curly brackets and any spaces between ~html and the opening curly bracket are ignored.
~latex or ~l	introduces a sequence of information in LaTeX; the information must be placed within curly brackets and any spaces between ~latex and the opening curly bracket are ignored. The information may itself contain curly brackets. These are assumed to be paired according to the usual rules of LaTeX, except that any curly brackets preceded by the LaTeX escape character \are ignored.
~plain or ~p	introduces a sequence of information to be inserted only in plain-text output; the information must be placed within curly brackets and any spaces between ~plain and the opening curly bracket are ignored.
~rtf or ~r	introduces a sequence of information in RTF; the output must be placed within curly brackets and any spaces between ~rtf and the opening curly bracket are ignored. The information may itself contain curly brackets. These are assumed to be paired according to the usual rules of RTF, except that curly brackets preceded by the RTF escape character \are ignored.

The DREPRESENTATION parameter is used to specify how to print numbers that represent dates and times. The DECIMALS parameter is then ignored. The setting of DREPRESENTATION is either a scalar indicating a predefined format, or a string defining a custom format. The string for a custom format contains a sequence of keys to represent the required components of the date and time. The available keys are:

d	day number within the month, using the minimum number of digits (e.g. 3, 12)
dd	day number within the month, using two digits (e.g. 03, 12)
dth	day number with one digit and suffix (e.g. 3rd, 12th)
m	month number, using the minimum number of digits
mm	month number, using two digits
mmm	abbreviated month name (Jan, Feb, Mar, Apr, May, June, July, Aug, Sept, Oct, Nov, Dec)
mmmm	month name in full
yy	year as a two-digit number (omitting the century)
yyyy	year as a four-digit number (including the century)
weekday	day of the week (Monday, Tuesday, and so on)
wday	abbreviated day of the week (Mon, Tue, Wed, Thur, Fri, Sat, Sun)
time24	time, including seconds, using a 24 hour clock
time12	time, including seconds, using a 12 hour clock (with a.m. and p.m.)
time100	time, using 24 hour clock and including hundredths of seconds
hours	elapsed time in hours, minutes and seconds
hours100	elapsed time in hours, minutes, seconds and hundredths of seconds
minutes	elapsed time in minutes and seconds
minutes100	elapsed time in minutes, seconds and hundredths of seconds
seconds	elapsed time in seconds
seconds100	elapsed time in seconds and hundredths of second

You can also insert one or more separators between the keys, any combination of space ( ), slash (/), hyphen (-) and comma (,).

Note: the operation of the 2-digit representation of a year is controlled by a “break point”. This has the initial default of 30, but that can be changed by the YEAR2DIGITBREAK option of SET, or in the DateFormat tab of the Options menu in Genstat for Windows. With the initial default of 30, for example, years from 1930 to 2029 will be represented as two digits, but others will be printed with four digits.

To simplify the specification of the most commonly used formats, a range of standard pre-defined formats are available. These are specified by supplying a scalar containing one of the numerical codes in the left-hand column of the table below.

You can also use the custom date formats supported by the client in Genstat for Windows. See the Date Formats page in the on-line help for details.

The SKIP parameter allows you to place extra spaces between the values of each structure. By default, no extra spaces are inserted unless a value fills the field completely, when a single space will be inserted; there is also a blank line before the first printed line. SKIP can be set to either a scalar or a variate in which a positive integer n requests that n spaces are left and a missing value can be used to request a blank line.

The values can be left-justified by setting the JUSTIFICATION parameter to left, or centred by setting it to center or centre.

The FREPRESENTATION parameter controls the printing of the factor values. By default Genstat will print labels if there are any; if there are none, it prints the levels. The ordinals setting represents the values by the integers 1 upwards.

The ORIENTATION option is relevant only when you are printing vectors or pointers. By setting ORIENTATION=across, the values are printed in alternate lines, across the page. To ensure that these line up correctly, the fieldwidth is taken as the maximum of those specified for the printed structures, while the field used to print their identifiers is given by the RLWIDTH option (by default 13).

When there is too much output to fit across the page, Genstat will print the output in more than one block unless option WRAP is set to yes. Then Genstat simply wraps each line onto subsequent lines. This is likely to be useful mainly if you are printing the contents of the structures to be read by another program. You might then also wish to suppress the identifiers by setting option IPRINT=* and remove blank lines by setting option SQUASH=yes.

The default option setting, IPRINT=identifier, will label the output with the identifier of the structure. Putting IPRINT=identifier,extra will also include any text that has been associated with the structure by the EXTRA parameter when it was declared, while the setting associatedidentifier can be used when a table has been produced by the TABULATE and AKEEP directives, to request that the output be labelled with the identifier of the variate from which the table was formed.

If you are printing vectors in parallel columns down the page, you can use the HEADING parameter to specify a text for each vector. This will then be used as a heading for that column, instead of the information requested by IPRINT. Note, though, that setting IPRINT=* will suppress any heading texts of the vectors as well as their identifiers.

The width of each line can be controlled by the WIDTH option; the default is to take the full available width. The INDENTATION option specifies the number of spaces to leave before each line; by default there are none.

The CHANNEL option determines where the output appears. By default, the output is placed in the current output channel, but CHANNEL can be set to a scalar to send it to another output channel; the correspondence between channels and files on the computer is explained in the description of the OPEN directive. Alternatively, you can set CHANNEL to the identifier of a text to store the output. The text need not be declared in advance; any undeclared structure that is specified by CHANNEL will be defined automatically as a text. Each line of output becomes one value of the text and if the text already has values they will be replaced. You are most likely to want to do this in order to manipulate the text further. Remember, however, that if you print the text later on, its strings will be right-justified by default, so you will need to set JUSTIFICATION=left in the later PRINT statement to achieve the normal appearance of your output. The maximum (and default) line length of this text is the length of what is called the output buffer. This is likely to be 200 on most computers. If you intend to print it to an output file, you should set the WIDTH option as appropriate.

The MISSING option allows you to specify a string to represent missing values, instead of the default that uses the asterisk symbol for missing numbers, and blanks for missing values in texts. For example, you could set MISSING='unknown' or MISSING=' '.

The VSPECIAL and TSPECIAL options allow you to substitute textual strings for other values of numerical structures. The values are specified, in either a scalar or a variate, using the VSPECIAL option. The TSPECIAL option then specifies a text, with as many values as the VSPECIAL scalar or variate, to define the strings to be printed instead. For example, in the following program, values of prob less than 0.001 are set to -1, and then printed as '<0.001'.

CALCULATE prob = prob * (prob .GE. 0.001) - (prob .LT. 0.001)
PRINT [VSPECIAL=-1; TSPECIAL='<0.001'] prob

PRINT can easily be used to print matrices and tables, by taking the default layout and labelling. For tables with more than one dimension, the usual layout has one factor across the page and the others down the page; tables with only one dimension are printed down the page. Several tables can be printed in parallel, provided they all have the same classifying factors. The tables are then printed in alternate columns, as though they formed a larger table with an extra factor (called the table-factor) representing the list of tables. This extra factor thus becomes another (in fact, the final) factor to be printed across the page.

This default layout can be changed using the ACROSS, DOWN and WAFER options. You may wish to do this simply by changing the factors which appear down and across the page. The ACROSS option can be set to a scalar to specify how many factors should be printed across the page, or to a list of factors to say which ones they should be. DOWN similarly specifies the factors to be printed down the page. However, you cannot specify a list of factors for one of these options and a scalar for any of the others. The table-factor can be represented in these lists by inserting a * in the required position; if you do not mention the table-factor in either list it remains as the last factor in the ACROSS list.

The WAFER option allows you to split the output up into subtables or “wafers”. This is particularly useful if the tables have many classifying factors, or if the factors have very long labels. The setting can again be either a scalar or a list of factors (possibly including the table-factor). Each subtable has a heading indicating its position in the full table. If the table-factor is included in the wafer, the identifier of the appropriate table will be printed at the beginning of the label for that wafer; this does not mean that the table-factor itself has been moved, simply that the labelling has been rearranged to make it easier to read.

You need not specify all the options DOWN, ACROSS and WAFER. If you leave any of them out PRINT will deduce the missing information.

When a table has margins, usually they will all be printed. However, you can control which are printed, by specifying the following settings of the PMARGIN option:

full	print all margins (default),
columns	print margins over column factors,
rows	print margins over row factors, and
wafers	print margins over wafer factors.

The OMITMISSINGROWS option also operates only on tables; if you set it to yes, PRINT will omit any lines of output where the tables contain only missing values.

You can control the space allowed for labels of the DOWN factors by using the RLWIDTH option. By default this is set to 13, but you might want something else if the labels are very small. If the width provided (by you, or implicitly) is inadequate, PRINT automatically resets it to accommodate the longest row label. The labelling of rows by the down factors is controlled by the RLPRINT option. The default, RLPRINT=labels,identifiers, prints the identifiers of the factors and their levels or labels. Similarly, the CLPRINT controls the labelling of columns by the across factors.

When tables are produced by TABULATE Genstat sets an internal indicator for use by PRINT to indicate the appropriate label for any margins. When a single table is printed this name will be used by default. When printing tables in parallel, if they all have the same setting of the margin name indicator, the appropriate name is used. If they have different settings, or none at all (tables from sources other than TABULATE) the margins will be labelled Margin by default. You can change the label by setting the MNAME parameter. Tables printed in parallel must have the same label throughout, and Genstat will take the one specified for the first table in the list. But in serial printing, you can use a different margin name for each table.

The TABULATE and AKEEP directives also record the identifier of the variate from which the table was formed, and you can request that this be used to label the output, instead of the identifier of the table itself, by setting the IPRINT option to associatedidentifier.

The PUNKNOWN option controls the printing of the “unknown” cell of a table. The default action is to print this cell, labelled with the table identifier, but only if it contains a value other than missing value or zero. You can select one of five settings:

present (default)	print value if not missing or zero
always	print the unknown cell regardless of value
zero	print unless the value is zero
missing	print unless the value is missing
never	do not print the unknown cell whatever its value

Genstat tables can only contain numbers. However, you can use the TLABELS parameter to print tables of textual strings. You first need to form a Genstat text structure containing all the strings that may occur. Then form a table with the required classifying factors and, in each cell of the table, put the number of the line (within the text) of the string that you want to print there. For example

FACTOR [LABELS=!t(April,May,June)] Month
TEXT [VALUES=North,South,East,West] Direction
TABLE [CLASSIFICATION=Month; VALUES=12.2,5.8,10.7] MeanSpeed
& [VALUES=4,2,4] MainDirection
PRINT MeanSpeed,MainDirection; TLABELS=*,Direction

will print 'West' in the first and third cells of the table for MainDirection (April and June), and 'South' in the second cell (May).

Options ACROSS, DOWN, WAFER, RLPRINT and CLPRINT also apply to matrices. By default, though, if you have several matrices they will be printed one after another on the page.

With symmetric matrices the only options of these that are relevant are RLPRINT and CLPRINT; a further setting integer is available for these to request that the rows or columns be labelled by the integers 1 onwards, as well as, or instead of the labels provided with the symmetric matrix: for example setting RLPRINT=integers and CLPRINT=integers, labels would identify the rows by integers and the columns with integers and labels.

The UNFORMATTED option can be used to send output to unformatted files. These can store values of data structures, so that they can later be input again using READ. This provides a convenient of way to free some space temporarily. It can also save computing time if you have a large data set that may need to be read several times. Input from character files is slow. So after vetting a large data set, it will be read more efficiently on future occasions if you transfer its contents to an unformatted file. As an alternative you could use backing store, but this stores the attributes of the structures as well as their values, and so access will take longer. You can also use these facilities to transfer data between Genstat and other programs. The only other options that are relevant to unformatted files are CHANNEL, REWIND and SERIAL. Genstat automatically creates an unformatted workfile, on channel 0, to which unformatted output is sent by default (by PRINT), and from which unformatted input is taken by default (by READ). This file is deleted automatically at the end of a Genstat run. It is usually quicker to read and write structures in series. Also the values of the structures transferred in parallel must all be of the same mode. Neither texts nor factors can be stored in parallel with values of the other, numerical, structures: scalars, variates, matrices or tables. As an example, we first open a file, and declare some variates, matrices and factors.

OPEN 'BDAT'; CHANNEL=3; FILETYPE=unformatted
VARIATE X,Y,Z; VALUES=!(11...19),!(21...29),!(31...39)
MATRIX [ROWS=2; COLUMNS=3; VALUES=11,12,13,21,22,23] M
FACTOR [LEVELS=3; VALUES=1,3,2,3,1,2,2,2,1,3] F

The next three statements store data for M and F on the file named BDAT and data for X, Y and Z (in parallel) on the workfile.

PRINT [CHANNEL=3; SERIAL=yes; UNFORMATTED=yes] M,F
PRINT [UNFORMATTED=yes] X,Y,Z

You can now free the space for numerical data for other purposes, by putting

DELETE X,Y,Z,F,M

By rewinding the files we can read the data back into Genstat.

READ [UNFORMATTED=yes; REWIND=yes] X,Y,Z
READ [CHANNEL=3; SERIAL=yes; UNFORMATTED=yes; REWIND=yes] M,F

You can also re-use the external file BDAT in a later job. If you change the lengths of structures, you must remember to reset them to their original values before you use unformatted READ to recover the data values from the file. Only the data values are stored in unformatted files, and not the attributes (such as lengths) as in backing-store files.

The style in which the output is generated will depend on how the channel has been opened (see the OPEN directive). An ordinary output file (i.e. one with option UNFORMATTED=no) may have been opened to take output as either plain text, HTML (as used for example by web browsers), RTF (as used by word processors such as Microsoft Word) or LaTeX. Plain-text output assumes that all characters occupy an equal width, so columns are aligned by use of space characters. The other styles use special codes to define the columns. However, you can set option STYLE=plain to request that output to files with these other styles should use spaces instead. This is useful particularly in procedures, when you may want to print a “sentence” containing information from several different data structures. The output of blank lines is still controlled by the SQUASH option.

Options: CHANNEL, SERIAL, IPRINT, RLPRINT, CLPRINT, RLWIDTH, INDENTATION, WIDTH, SQUASH, MISSING, ORIENTATION, ACROSS, DOWN, WAFER, PUNKNOWN, UNFORMATTED, REWIND, WRAP, STYLE, PMARGIN, OMITMISSINGROWS, VSPECIAL, TSPECIAL.

Parameters: STRUCTURE, FIELDWIDTH, DECIMALS, CHARACTERS, SKIP, FREPRESENTATION, JUSTIFICATION, MNAME, DREPRESENTATION, HEADING.

Action with RESTRICT

You can restrict any vector (variate, factor or text) to specify that only a subset of its units should be printed. When printing in series the vectors can be restricted to different subsets; but with parallel printing any restriction is applied to all the vectors (and any pointers) so, if more than one vector is restricted, they must all be restricted in the same way.

See also

Directives: CAPTION, COPY, OPEN, PAGE, SKIP, DUMP, LIST.

Procedures: DECIMALS, MINFIELDWIDTH.

Commands for: Input and output.

Example

" Example PRIN-1: Controlling the display of tabular output"

" By default, structures are printed in parallel if possible."
VARIATE [VALUE=1...5] Line
TEXT Poem; VALUES=!T(\
'Doctor Foster went to Gloucester
All on a summer''s day.
He stepped in a puddle
Right up to his middle
And never went there again.')
PRINT Line,Poem

" Output can be customized with many options. 
  1) Control the number of decimal places
     (the setting is immaterial for texts)"
PRINT Line,Poem; DECIMALS=0,*

" 2) Control the fieldwidth used for a value"
PRINT Line,Poem; DECIMALS=0; FIELDWIDTH=1,*

" 3) By default, each field is separated from the last by at
     least one blank, but this can be cancelled with SKIP"
PRINT Line,Poem; DECIMALS=0; FIELDWIDTH=1,*; SKIP=0,0

" 4) Left-justify the text"
PRINT Line,Poem; DECIMALS=0; FIELDWIDTH=1,*; JUSTIFICATION=right,left

" 5) Remove the headings"
PRINT [IPRINT=*] Line,Poem; DECIMALS=0; FIELDWIDTH=1,*; JUSTIFICATION=left

" 6) Remove the blank lines"
PRINT [IPRINT=*; SQUASH=yes] Line,Poem; DECIMALS=0; FIELDWIDTH=1,*;\ 
  JUSTIFICATION=left

" If structures are of different sizes or shapes, printing is automatically
  switched to serial."
VARIATE [VALUE=1...4] Newline
PRINT Newline,Poem

" A vector in a list of incompatible structures like
  this will be printed across the page.  Thus the above PRINT
  statement is interpreted as if it had been written in
  the following form:"
PRINT [SERIAL=yes; ORIENTATION=across] Newline,Poem

" Scalars are treated as vectors of length 1, and so can be printed
  in parallel with other vectors of length 1.
  In a section heading for output it may be convenient to give
  a text or number explicitly in the PRINT statement."

CALCULATE Nline = NVALUES(Poem)
PRINT 'The poem has',Nline,'lines in it'

" This would look better with a little formatting, and with
  structure names omitted. Note that if you use SKIP you have to
  provide your own blank lines at the start of your output.  Any
  attempt to put blank lines between structures printed in parallel
  will be ignored."
PRINT [IPRINT=*; SERIAL=yes; ORIENTATION=across]\ 
  'The poem has',Nline,'lines in it';\
  FIELDWIDTH=1; DECIMAL=0; SKIP=!(*,*,0),1,1

" The output channel may be a file or a text vector (which need
  not be declared in advance).  There is currently a limit of 
  160 characters per line on a text vector produced by PRINT,
  but if this structure is to be printed, a sensible page width
  should be specified."

PRINT [IPRINT=*; SQUASH=yes; CHANNEL=Ptext] Line,Poem;\ 
  DECIMALS=0; FIELDWIDTH=1,*; JUSTIFICATION=left

" Ptext is a text, which will be printed right-justified by default."
PRINT Ptext

" Left-justify, and remove the column heading."
PRINT [CLPRINT=*] Ptext; JUSTIFICATION=left