Returns to a previous input stream (text vector or input channel).
||Number of streams to ascend; default 1|
||Whether to close the channel (or text) after the return (
||Whether to delete the text or the file to which the channel was attached (only relevant if
|expression||Logical expression controlling whether or not to return to the previous input stream; default 1 (i.e. true)|
In its simplest form, you can type
to make Genstat stop taking statements from the current input channel and to go back to the channel that was previously active, and contained the
INPUT statement that switched to the current file. Input then continues from the line following the original
INPUT statement, but a marker is left in the channel that contains the
RETURN statement, so that you can use
INPUT to continue from the next line after
RETURN later in your programme.
Sometimes you may want to return only if a particular condition is satisfied, for example if you have discovered that the data are unsatisfactory for whatever operations occur later in the file. To do this, you set the parameter to an appropriate logical expression; this must return a scalar result, which is interpreted as true if it is equal to 1, and false otherwise. For example
If you have use
INPUT several times, you may wish to return through several channels. The
NTIMES option can be set to a number, or a scalar, to control how many returns take place. For example, with input starting on channel 1, supposing you had used
INPUT 2 to switch to a file on channel 2, and then
INPUT 3 to switch to a further file (on channel 3). If this file then contained the statement
RETURN [NTIMES=2] you would return to channel 1. You can never return from input channel 1, so if you set
NTIMES to a number greater than the number of currently active input channels, Genstat simply returns to channel 1.
You can set option
CLOSE=yes to close the file; also, if you do have
CLOSE=yes, you can set
DELETE=yes to delete the file.
If Genstat meets the end of the file on the current input channel, it will try to return control to the channel from which it was called. This is called an implicit return. The channel is closed automatically when this happens, and a warning message will be printed.
In order to maintain control over the different input channels, and know where to go after a
RETURN, Genstat keeps an internal stack of input channels. Suppose you specify channel k, by typing
INPUT k. There are three possible actions:
(a) if k is the current input channel, the statement is ignored;
(b) if k is not in the stack, it is added to it;
(c) if k is already in the stack (that is, the current state is: 1 → … → k → k1 → k2 → … → kn) then the intermediate channels k1 … kn are suspended at their current positions and removed from the stack.
Input then switches to channel k, taking statements from the beginning of the file if it has never been used before, or from the point at which it was last suspended. Subsequent
INPUT statements will re-start the other channels from where they were suspended. When a
RETURN statement is used, Genstat steps back
NTIMES through the stack, removing any intermediate channels from the stack. This means that, using the above representation of the input stack, if channel kn contained the statement
INPUT k2 and channel k2 then had a
RETURN, this would return to channel k1.
If you use
## to execute macros, these are treated in the same way as input channels and added to the input stack. You can use
INPUT to temporarily halt a macro and switch to a file, and
RETURN to get back to the macro.
Commands for: Input and output.