Returns to a previous input stream (text vector or input channel).
Options
NTIMES = scalar |
Number of streams to ascend; default 1 |
|---|---|
CLOSE = string token |
Whether to close the channel (or text) after the return (yes, no); default no |
DELETE = string token |
Whether to delete the text or the file to which the channel was attached (only relevant if CLOSE=yes) after the return (yes, no); default no |
Parameter
| expression | Logical expression controlling whether or not to return to the previous input stream; default 1 (i.e. true) |
|---|
Description
In its simplest form, you can type
RETURN
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
RETURN MIN(Height)<0
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.
Options: NTIMES, CLOSE, DELETE
Parameter: unnamed.
See also
Commands for: Input and output.