. (Dot - TCL Stacker Recall Command)

The TCL Stacker Recall Command allows you to recall a previously executed command for re-execution or modification. Commands are stored in a stack, with the last command executed on the top.

Command Class

TCL Stacker Processor.

Syntax

.{command}

Syntax Elements

. The character that runs the TCL Stacker Recall command. By default a dot (.) is used, but this can be changed to any printable ASCII character with the SET-STACK command.

command A TCL Stacker command. If omitted, the TCL Stacker Recall command enters the line editor and displays the last TCL command executed.

Comments

Once editing the command stack, you can modify any command and enter new commands. On exit, you can choose to execute the currently selected command. Use of the editor with the TCL Stacker is described in Using the Editor below.

The TCL stack is cleared whenever you log off. However, you can save it with the editor FS command and subsequently restore commands using the editor ME command.

Configuration Options

By default, the stack length is 20 entries – you can change this with the SET-STACK command or by using the set stack size TCL Stacker command.
You can suppress the TCL Stacker by using the .O command or the S option to SET-STACK, or by specifying a stack length of 0.

You can optionally save TCL commands called from within Procs, DataBasic programs (including those in nested contexts such as triggers), and Reality SQL on the command stack. These are separately controlled as follows:

Environment	Controlled by	Default
Proc	.P SET-STACK (P	Off
DataBasic (PERFORM).	.C SET-STACK (C	Off
Reality SQL	.W SET-STACK (W	On

Environment

Controlled by

Default

Proc

SET-STACK (P

Off

DataBasic (PERFORM).

SET-STACK (C

Off

Reality SQL

SET-STACK (W

You can have TCL commands automatically converted to upper case (default, off). This option is controlled by the .T and .U TCL stacker commands.
You can use the .Y stacker command or the Y option to SET-STACK to specify whether commands already on the stack are moved or copied to the top of the stack when they are reused (default, move).
You can enable or inhibit a check for a trailing ESC character by using the .F TCL stacker command or the F option to SET-STACK (default, on). If enabled, TCL commands that end in a trailing ESC character are added to the command stack (without the ESC), but not executed; this allows you to save and edit complex commands that have been mistyped, without attempting to run them. Otherwise, the system attempts to execute the command and places it on the stack with its trailing ESC.
You can use the .Z TCL stacker command or SET-STACK to change the stacker command character to any printable ASCII character.

Commands

The commands available depend on the MutliValue environment selected (set with the DOT/Stacker environment option in SSM Option 4 – Define Environment Settings). For descriptions, select the emulation you require from the drop down list below:

.? Display help for the TCL Stacker.

.{position} Enter the editor at the stacked command at position (default, top of stack). Stack positions number from 1.

..{position} Execute the stacked command at position (default, top of stack). The specified command is displayed and executed without entering the editor.

..commandList Execute the specified stacked commands. commandList is a comma-separated list of stack positions.

.ESC Toggles save without command execution when the command line ends with an ESC character. ESC is the ESC character, entered by pressing esc or CTRL+[. See also .F.

.! string Find the first command containing string and run that command.

.A{range}/string Append string to the commands in range.

.B{range}/string Split the commands in range before string. Similar to the SP (Split) Editor command.

.C Toggle saving of commands run from within DataBasic programs.

.CL Clear the stack.

.C{O}commandList {(options}
Copy the specified commands to a file item. commandList is a comma-separated list of stack positions.

options

A All commands are copied (commandList is ignored and can be omitted).

O Overwrite item if it exists (same as CO).

P Copy to Printer.

T Copy to Terminal.

X Copy in Hexadecimal mode. Use in combination with P or T.

Prompts for a destination in a similar way to the COPY command. You must provide a file-specifier (preceded by an open parenthesis) or an item-id, or both:

With just an item-id, the specified item is created in the MD of the account.
With just a file-specifier, an item called Tstacker is created in the specified file.
With both a file-specifier and an item-id, the specified item is created in the specified file.

.DE{range}{/string}
Delete the commands in range that contain the text string. If string is omitted, all commands in range are deleted.

.E{position} Enter the editor at the stacked command at position (default, top of stack). Stack positions number from 1.

.F Toggles the option to save without command execution when the command line ends with an ESC character.

.Gposition Move the command at position to the top of the stack.

.H Display help for the TCL Stacker.

.I{range}/string Insert string at the beginning of all commands in range.

.J{range}{/string{/}}
Joins commands in range, inserting string between them. Similar to the J (Join) Editor command.

.K{range}{/string} Kill/delete the commands in range that contain string. If string is omitted, delete all commands in range.

Note: If range is a single number, it specifies a position rather than a line count (cf. Range Parameter).

.L{range}{/string} List the commands in range that contain string. The default, if range is omitted, is 20 commands. If string is omitted, display all commands in range.

.LOAD file-specifier item
Add the commands from the specified item to the top of command stack without executing them. If you omit file-specifier, the item is assumed to be in the MD of the account.

.M{U}{range}{U}/string/{replacement{/}{startCol{-endCol}}}{*}
Replace string with replacement in the commands in range.

If columns startCol to endCol are specified, string must exist within these columns (see Column Dependent Matching).

If U or trailing * is specified, all occurrences of string in each command are replaced.

.O Switches the TCL command stack On or Off (toggle). If you disable the stack all stacked commands are discarded.

.P Toggles the option to save commands from within Procs.

.Q Display the status of the TCL command stack. The same as running SET-STACK without any options.

.R {file-specifier} item
Add the commands from the specified item to the top of command stack and execute them. If you omit file-specifier, the item is assumed to be in the MD of the account.

.R {file-specifier} item (L
Add the commands from the specified item to the top of command stack without executing them. If you omit file-specifier, the item is assumed to be in the MD of the account.

.R{position} Enter the editor at the stacked command at position (default, top of stack). Stack positions number from 1.

.R{U}{range}{U}/string/{replacement{/}{startCol{-endCol}}}{*}
Replace string with replacement in the commands in range.

If columns startCol to endCol are specified, string must exist within these columns (see Column Dependent Matching).

If U or trailing * is specified, all occurrences of string in each command are replaced.

.S{count} Set the size of the TCL command stack to count (0 to 500). If count is zero, the stacker is switched off; if greater than zero, it is switched on. If you omit count, the current status of the TCL command stack is displayed.

Note: If you reduce the size of the stack, all stacked commands in positions greater than the new size are discarded.

.Srange {(options}
Copy the commands specified by range to a file item. Accepts the same options and prompts for a destination in the same way as the .C stacker command.

.SIZE{count} Set the size of the TCL command stack to count (0 to 500). If count is zero, the stacker is switched off; if greater than zero, it is switched on. If you omit count, the current status of the TCL command stack is displayed.

Note: If you reduce the size of the stack, all stacked commands in positions greater than the new size are discarded.

.T Toggles the option to automatically convert commands to uppercase as they are saved on the stack. Quoted strings are not affected.

.U Toggles the option to automatically convert commands to uppercase as they are saved on the stack. Quoted strings are not affected.

.U{range} Force commands in range to uppercase, including quoted strings.

.V{range} Force commands in range to uppercase, including quoted strings.

.W Toggles the option to save commands from within Reality SQL.

.X{position} Execute the stacked command at position (default, top of stack). The specified command is displayed and executed without entering the editor.

.XcommandList Execute the specified stacked commands. commandList is a comma-separated list of stack positions.

.X {file-specifier} item
Add the commands from the specified item to the top of command stack and execute them. If you omit file-specifier, the item is assumed to be in the MD of the account.

.X {file-specifier} item (L
Add the commands from the specified item to the top of command stack without executing them. If you omit file-specifier, the item is assumed to be in the MD of the account.

.Y Toggles the option to move or copy reused commands to the top of the stack (see Configuration Options).

.Zcharacter Changes the command Dot character from . to character (see also SET-STACK).

Range Parameter

The range parameter can be any of the following:

Range	Selected Commands
omitted	Operate on top stack entry.
`count`	Operate on the first `count` stack entries.
`position`	Operate on stack entry `position`.
–`position`	Operate on stack entries 1 to `position`.
`position`–	Operate on stack entries `position` to the end.
`first`–`last`	Operate on stack entries `first` to `last` inclusive.
`line1`–`line2`	If `line1` < `line2`, operate on stack entries `line1` to `line2` inclusive. If `line1` > `line2`, operate on stack entries `line2` to `line1` inclusive.
`first`,`count`	Operate on `count` stack entries starting with entry `first`.
`count`,`first`	Operate on `count` stack entries starting with entry `first`.

Note that stack positions number from 1.

String Delimiters

When using commands that include a string parameter, a delimiter is used to separate the different syntax elements. It can be any nonnumeric character, except a space or minus sign, that does not appear in the search or replacement text. The slash (/) character is the most commonly used character for a string delimiter and is used in the command descriptions.

In the .DE (Delete), .K.K (Kill/delete) and .L (List) commands, using the hash (#) as a delimiter negates the search; only lines that do not contain the search text are deleted or listed.

Note that, when used as a delimiter, the colon (:) anchors the search to the starting column (see Column Dependent Matching).

String Matching

The caret can be used as a wildcard character in search strings in a similar way to in the editor. Refer to the section Wildcard Character in the Editor Reference for details.

If the mvEnterprise environment is selected, the following special characters must be used for string matching:

Syntax	Result
`string`	Matching command must exactly equal `string`.
`string`]	Matching command must start with `string`.
[`string`	Matching command must end with `string`.
[`string`]	Matching command must contain `string`.

Using the Editor

Editor commands in the TCL Stacker execute as described in the Editor Reference, with the following exceptions.

FI Saves the TCL commands currently stacked and executes the current line of the stack.

If you change the sequence of commands by using a DE (Delete), I (Insert), ME (Merge), or SP (Split Line) command and then enter the FI command, the commands in the stack are saved, but no command is executed.

To execute a command after changing the sequence of commands in the stack, either:

Enter F to update the buffer and then use FI to execute the top stack command.
Enter the line number of the command to execute and then use FI.

FS Saves the TCL commands currently stacked and exits to TCL.

FS (file-name item-id
Saves the TCL commands currently stacked to the specified file. The file must already exist in the current account, but the specified item must not exist. The commands in the stack remain unchanged.

Note: All other forms of the FS command are invalid.

FD Not supported for editing the TCL Stacker lines.

All other Editor commands execute in the normal way. For example:

EX Exit the TCL Stacker without saving changes or executing a command.

L99 Lists the commands in the TCL stack.

Example 1

To edit the command on line '2' and save the edit:

:.2
002 LIST CUST BY NAME NAME ADDR
.R/LIST/SORT
002 SORT CUST BY NAME NAME ADDR
.FS

:

The last entry (FS) files the edited command. Note, however, that the edited command is not executed.

Example 2

To re-execute the last command executed:

:..
001 SORT MD

Note that the .. command is equivalent to .X, ..1 and .X1.

Example 3

To re-execute the command on line '2':

:..2
002 LIST MD

Note that .X2 produces the same result.

Example 4

The example that follows assumes that you have already entered the editor, by entering the TCL Stacker command at the TCL prompt.

To list the lines in the stack, type L at the dot prompt, followed by the number of lines to list. Having displayed line 1, you can display the remainder of the stack by entering:

.L99
002 SORT CUST BY NAME NAME ADDR
003 SORT MD WITH 2 = "35"
004 LISTFILES
005 WHO
006 CREATE-FILE STACK-TEST 3 1
EOI 006
.

To list lines 2 to 4, again assuming you have displayed line 1, enter:

.L3
002 SORT CUST BY NAME NAME ADDR
003 SORT MD WITH 2 = "35"
004 LISTFILES
.

To locate the line containing the text "STACK-TEST":

.L/STACK-TEST/
006 CREATE-FILE STACK-TEST 3 1
.