UserDoc:Shell

What is a shell?

Two shells console window

The Shell/Console is a text based window that provides a mechanism for the user to send commands to the operating system or run user programs. It is a low-level version of the Graphical User Interface (GUI) known as the Workbench. Some commands are unique to the Shell, just as some are unique to the Workbench. In practice, the two user interfaces complement each other with a large amount of overlap. The choice is left to personal taste.

The user-supplied commands and responses from the Shell and other programs can be displayed in a Console text window on the screen. This window can be a simple one with a few features or complex ones with different tabs (see picture), an automatic display history or other features that give a better user experience. You can open only one shell in a window, or open different shells in the same console window. If you decide to work with different shells, each one you start will be opened in a different tab in the same console window. Each shell is independent and you can navigate between each of them by a keyboard shortcut or menu item.

Alternatively, the user interface may be used via a remote mechanism such as a terminal program running on another computer. Such a remote machine might be connected via a serial interface, a network connection or other means.

Starting, closing and customising a shell

Opening a Shell with default settings

You can open a shell doing like this:

• Double click the Shell icon that you can find in the System folder of the system partition.

• Issue one of the following commands newshell, newcli or cli. As an example, you can use such command in the Execute... requester of the Workbench.

Opening a shell defining its attributes

If you issue the newshell command without an argument, the default value will be used and a shell will be opened positionned at the top left of the screen, with a height of 130 pixels and it will take the width of the screen. The newshell command can also be used with a special argument that describes how the shell should look. This is the WINDOW template that looks like this:

CON:[X]/[Y]/[width]/[height]/[title]/[options] where:

X

is the number of pixels from the left edge of the screen to the left border of the console window. Use no value (i.e. //) to specify the minimum possible pixels. Use the value -1 to generate a window that is centred horizontally on the screen.

Y

is the number of pixels from the top of the screen to the top of the console window. Use no value (//) to specify the minimum possible pixels. Use the value -1 to generate a window that is centred vertically on the screen.

width

is the width of the console window, in pixels. Use no value (//) to specify the full width of the screen.

height

is the height of the console window, in pixels. Use no value (//) to specify minimum possible height.

title

is the text that appears in the console window title bar. Note that if you want to use a title with spaces in it you need to enclose the whole specification line in double quotes ("). This is the same as using file names with spaces.

You can incorporate "formatting" descriptors in the title. These will expand at run time to show different text in the Window title. The following format descriptors are the same as those available for the command prompt.

%E

Displays the execution time of the last program run; this is given as the number of seconds, followed by the decimal point, and the fraction of a second. This corresponds to the value of the $_RunTime environment variable.

%N

Displays the Shell number. This is also available in the form of the Process environment variable.

%R

Displays the return code for the last operation. This is also available as the $RC environment variable.

%S

Displays the current directory (full path).

%W

Displays the error code set by the last operation; this is what the WHY command will print the corresponding error message for. This is also available as the $Result2 environment variable.

These additional format descriptors are unique to the console:

%D

Displays the date in the Locale form.

%F

Displays the number of rows of display history filed to disk.

%H

Displays the number of rows of display History in the text buffer.

%s (lower case)

Displays the current directory (last part only).

%T

Displays the current time.

Use slashes (/) to separate the parameters and options.

options

You can use here any of the following options:

AUTO

The window automatically appears when the program needs input or produces output. Selecting the Shell's close gadget closes the window, but it re-opens immediately since it is expecting input.

ALT

The window appears in the specified size and position when the zoom gadget is clicked. The four parameters must be separated with slashes (for example, ALT 30/30/200/200). If the ALT option is not specified, the alternative window size is full screen.

BACKDROP

The window appears on the backdrop, behind all the Workbench windows. This console window cannot be brought to the front of the screen; you have to resize the Workbench windows to see it.

CHARSET

The window font will be opened with the specified charset if possible. The charset is specified as a string, eg: CHARSET=ISO-8859-15.

CLOSE

The window has all the standard gadgets, including a close gadget.

COLUMS

Specify the number of columns of text in the window to be opened, given as the number of characters rather than as pixels. This option overrides the width parameter of the window specification.

INACTIVE

The window opens, but is not made the active window.

LEGACY

This option forces the window to be opened without history, ClickTab or a scrollbar. It might be useful to use with older, non-conforming applications that use the console. If this option and the TABBED option are both present on the command line, the LEGACY option will take precedence.

The NOHISTORY option is a synonym for this option but can be over-ruled by a later TABBED option. Refer also to the notes for the TABBED option. Please see the section below to understand why this LEGACY mode exists.

NOAPPWINDOW

The window is not registered as an AppWindow, so you can't drop icons onto it.

NOBORDER

The window opens without any left or bottom window border. Only the zoom, depth and sizing gadgets are available.

NOCLOSE

The window does not have a close gadget. If you open a console normally, there is no close gadget. If you open a console using the AUTO option, there is automatically a close gadget on the window.

NODEPTH

The window has no window depth gadget.

NODRAG

The window cannot be dragged. It has zoom, depth and sizing gadgets, but no close gadget.

NOICONIFY

The window is opened without an iconify gadget. The window can still be iconified by use of the Right-Amiga I keyboard shortcut or the corresponding menu item.

NOSIZE

The window has no size gadget.

NOSCROLLBAR

The window opens without a scrollbar in the right border. This option is forced if the LEGACY option is specified.

ROWS

Specify the number of rows in the window to be opened, given as the number of characters rather than as pixels. This option overrides the 'height' parameter of the window specification.

SCREEN

The window opens on a public screen. The screen does not have to be already open. You specify the name of the screen after the SCREEN keyword. You can interpose spaces or one "=" sign between the SCREEN keyword and the screen name. For instance, all these four versions work the same:

SCREENScreenName

SCREEN ScreenName SCREEN=ScreenName SCREEN = ScreenName

If the window is to open on the frontmost public screen, use two * (asterisks) in place of the screen name. Note that a single asterisk will be "swallowed" by AmigaDOS before the con-handler sees it, so two are required.

SIMPLE

If you enlarge the window, the text expands to fill the new available space, allowing you to see text that had been scrolled out of the window (this is the default behaviour).

TABBED

The window is opened with a ClickTab gadget, allowing subsequent Shells to share the window frame. The currently visible and active Shell may then be selected by clicking on the Tab gadget or by using a keyboard shortcut. Closing individual Shells (one at a time) does not close the Tabbed window until all Shells have been closed, but you can close all Shells at once by holding the Shift key whilst clicking the Close gadget. This option is not available with a pre-existing Window.

If the window is opened with History enabled (i.e. without the LEGACY option), but the TABBED option is omitted, you can still open multiple Shells in the window, but there will be no ClickTab gadget. You will have to use the Right-Amiga < and Right-Amiga > shortcut keys or the menu Select item to switch the display from one Shell to another.

Default: Not tabbed.

WAIT

The window can only be closed by selecting the close gadget or entering Ctrl-\. If WAIT is specified without the CLOSE option, there is no close gadget and the window can only be closed by typing Ctrl-\.

WINDOW

This option is intended for use by applications only and is of limited use to a user.

A window previously opened through intuition.library/OpenWindow or intuition.library/OpenWindowTagList should be attached to the new console. The window's address must be given as a parameter given as a hexadecimal number. Any leading "0x" prefix is ignored. Note that History and multiple Shell features can not be used with an existing window.

Example:

newshell "CON:0/0//300/This is a shell/CLOSE"

Note: double quotes (") are used because there are spaces in the title string.

Legacy mode

There are two types of console window, the old legacy window and the new style with more features (which is the default). The old legacy window is maintained for compatibility with older programs and will not normally be used by a Shell. The legacy console does not support history or shared windows, does not have a menu and mimics as closely as possible the behaviour of the old con-handler and console (pre-AmigaOS 4.1 versions).

Shell in legacy mode

When running programs other than a Shell (for example, text editors or file display applications), you may find that some older programs do not behave as you would expect from experience with the old con-handler and console. In many cases older programs did not obey the documentation and relied on behaviour that is different in the new con-handler and console.

If you have a program that runs from a Shell and misbehaves, try running it from a legacy Shell/console. That can be done by specifying the LEGACY option in the NewShell command line or the tooltypes in the Shell icon.

Unless you choose otherwise, a new-style Shell window will have these features over the old style:

• Scrollbar for scrolling display history up and down
• Iconify gadget to Iconify the window;
• Menu that allows various attributes to be changed.

Note: the above features are optional and can be determined by the options on the command line when the Shell window is opened. The window can not be changed once it has been opened.

Defining preferences to customise the shell

The prefs editor allows you to select and save some preferences to be used as defaults when a Shell console is opened. Not all console settings can be chosen and some may be later over-ridden under program control. The Prefs editor can be run from the Prefs drawer, but can also be run from the console menu (present in a new-style console only). Some options in the editor are different for the two methods.

Note that some attributes of an already opened console window can not be changed immediately. If the current Shell is displayed in a window with Tabs, you can change the attribute from the preferences editor, then clone the Shell and the new Shell will show the modified attribute(s). These attributes are:

• Max lines in text buffer;
• Save history on exit;
• History drawer;
• Command buffer, kB.

The GUI shows several areas in the window, used to select settings of particular variables as defaults. There are three "pages" of settings, selected by clicking one or other of the Tabs at the top of the window.

    Appearance Page            
                     Text Font 
                  Cursor Style 
               ClickTab Labels 
             Emulation Options 
    Text Colors Page           
                       Palette 
              Foreground Color 
              Background Color 
                   Sample Text 
    Completion Page            
               Name Completion 
            Command Completion 
                 Other Options 
    Options Page               
               Display History 
                  Text Options 
         Save Settings Options 

Note: The preferences editor can be called from the console menu, if the console has been opened with the "History" or "Tabbed" attributes. You can exit from the preferences editor in the normal way with "Save", "Use" or "Cancel". If you select "Use", there are more settings that specify how the changed settings will affect other Shells and windows.

When making changes to the console attributes from the menu, be aware that attributes of the window layout can not be changed in the current window. If you wish to change one or more of these attributes, you must "Save" or "Use" the settings and specify that the changes are to apply to "Future Windows". The new attribute(s) (for example, "Box around Text") will then be used when future windows are opened.

Closing a shell

To Exit from a Shell, you can:

• Type EndCLI or EndShell at the command prompt;
• Type one of the keyboard shortcuts Ctrl \ or Right-Amiga K; or
• Click in the Close gadget (not all Console windows have a Close gadget, but it is normal for a Shell window to have one). If there are two or more Shells sharing this window, you can close them all at once by holding the Shift key and clicking the Close gadget. The keyboard shortcut Right-Amiga Q will also close all Shells at once.

Using a shell

A shell being a text only interface you will use it almost exclusively with the keyboard. You will type commands or use keyboard shortcuts to act on the shell. Also there are a few graphic elements that will require the use of a mouse: menu items, window sliders, tabs...

Shell features

A shell always features a command history. It allows you to check previous commands and issue them again.

By default a shell features a display history that allows you to scroll back in time and see what was displayed before. A scrollbar will allow display history to be scrolled back into the window. History can also be scrolled by Keyboard Shortcuts.

Any Console window (legacy or new style) can also be iconified, whereupon it shrinks into an icon on the Workbench. You can iconify the Shell window by any of these means:

• Click the Iconify gadget (if present) on the window top border;
• Type Right-Amiga I while the shell window is activated;
• Select Iconify from the console menu.

A single Console window can display any one of several Shells. The Shell currently in front can be changed by:

• Clicking on one of the Tabs in the ClickTab gadget (if used);
• Using a keyboard shortcut to go forward to the next or back to the previous Shell;
• Using a menu item to go forward to the next or back to the previous Shell;
• Using a menu item to directly select a different Shell.

When a different Shell is selected for display by one of the above means, the window changes to display the new Shell. The window Title bar, Scrollbar settings and text attributes all change to the settings of the new Shell.

Any other Shells displayed in the Console window continue with whatever they were doing and are not affected by the display change. You can bring any one of them to the front and it will behave as if it had merely been covered by another window.

Menus

Project menu

Some items in the Project menu may not appear, depending on the mode in which the window has been opened. These dependencies are listed with each item below.

• New shell

This option opens a clone of the Shell that was running at the time the menu item was selected. It is equivalent to the keystroke Right-Amiga N.

---

• Load history...

This item brings up an ASL requester, allowing you to select an ASCII file that will be read into the console as though it were command history. Any control characters or escape sequences embedded in the file will be actioned in the normal manner when loaded. Notes: display history files are saved without any formatting, therefore the text may not appear the same in the window as it did before being saved. The file is read simply as a string of text and any Shell commands in it are not recognised or actioned. Therefore, the con-handler's command history will not contain any of the saved commands in the display history file.

• Save history...

This item brings up an ASL requester, allowing you to nominate a drawer and file name under which to save the current display history. Notes: the display history is saved without any formatting codes. The history is not changed after the text is saved.

• Clear history

This item clears all display history except that which is in the current window. Any temporary disk files are also cleared.

---

• Iconify

this iconifies the shell into an icon on the Workbench screen. The icon will be named with the process ID of the shell. This is equivalent to the keystroke Right-Amiga I.

• About...

This gives the version numbers of the console.device and the console.handler. It is equivalent to the keystroke Right-Amiga ?.

---

• Close shell

This item issues a CLOSEWINDOW command (equivalent to typing Ctrl-\ or Right-Amiga K). It will close only the current Shell and will appear only when there are two or more Shells in the window. The window may not close if there are unfinished tasks running.

• Close all

This item closes every Shell operating in the current window. Some or all of the Shells may remain open if they have tasks still running. It is equivalent to the keystroke Right-Amiga Q.

Edit menu

• Copy - copies the selected text into the clipboard.
• Paste - pastes the text from the clipboard to the shell prompt.

View menu

• Prev shell

This item will only appear if you have more than one Shell open in the window. It will appear with or without a ClickTab gadget in the window. When selected, it changes the current Shell to the previous Shell, where "previous" refers to the Tabs in a ClickTab Window. If there is no ClickTab in this window, the "previous" Shell is that opened before the currently active Shell. If the current Shell is the first Shell opened, this item will select the last Shell opened. It is equivalent to the keystroke Right-Amiga <.

• Next shell

This item will only appear if you have more than one Shell open in the window. It will appear with or without a ClickTab gadget in the window. When selected, it changes the current Shell to the next Shell, where "next" refers to the Tabs in a ClickTab Window. If there is no ClickTab in this window, the "next" Shell is that opened before the currently active Shell. If the current Shell is the last Shell opened, this item will select the first Shell opened. It is equivalent to the keystroke Right-Amiga >.

• Select...

This item will only appear if you have more than one Shell open in the window. It will appear with or without a ClickTab gadget in the window. If you have two or more Shells open, the "Select" item will open a pop-up window showing you the names of each open Shell. The names are taken from the ClickTab Labels assigned in the Prefs editor. If you click on any named Shell in the list, that Shell will become the "front" Shell. You can close the pop-up window with the mouse or double-click on the name you want.

Settings menu

The Settings menu allows you to alter the Preferences of the current window. All Shells operating in that window will be affected by any changes you make.

• Edit...

This item calls the Preferences Editor. You may make any changes you wish, then Use, Save or Cancel them as you please. If you exit with "Save", they will be saved in ENVARC: and all consoles opened after that time will use the new settings. If you exit with "Use", additional prefs settings will decide whether the changes apply to this window only, this window and all future windows or future windows only. Additionally, if the current window has two or more Shells operating under different Tabs, you can specify whether the changes are to apply to the frontmost Shell only, or to all Shells within that window.

• Load...

This item opens an ASL requester that allows you to select a special settings file that you have saved somewhere. Its contents will affect only the current window.

• Save As...

This item opens an ASL requester that allows you to choose the drawer and file name under which the settings will be saved.

Extras menu

The Extras menu contains only the "Help" item.

• Help...

This item displays the console Help file with Multiview. It is equivalent to typing the keystroke Right-Amiga H or the Help or Scroll Lock keys.

Using the command history

The Command history is provided and maintained by the console. Note that this is the history of previous commands only, not the responses to them or any program output. Do not confuse it with the display history which you can scroll up and down with the scrollbar on the right.

Every input command you type is stored by the console and can be retrieved by the Up-arrow key. You can navigate up or down through the history using the Command History Shortcut Keys. When you reached a command you would like to execute again, just press the Enter key to validate. Note that whatever you type that remains on the display will be stored in the display history when it scrolls off the screen. So you could achieve the same effect by scrolling back the display history, selecting the desired command by clicking and dragging with the mouse, typing Right-Amiga C to capture it, then Right-Amiga V to paste it on the command line.

There is also a Shell command history that prints out all the commands you have entered since the Shell session began (but none of the responses or program output).

Using the display history

The Display history is only maintained if the console window is opened with a command line containing the option "History" or "Tabbed". The history can be saved after the Shell editing session. Refer to Console Prefs editor for details about saving the display history by default.

When one of the above options was specified on the Shell command line, the Console that is opened can maintain and display in a memory-resident buffer, any display lines scrolled off the top of the display. You have a choice of what (if anything) you want to save when the console is closed. This choice is selected in the Console Prefs editor. Lines of text (both commands and program output) that have scrolled off the top of the display may be scrolled back by any of these means:

• Use the mouse to click and drag the scrollbar;
• Use the mouse to click on the arrows at the bottom of the scrollbar;
• Use the mousewheel to scroll the display up or down;
• Use the keyboard Page Up or Page Down keys (only with PC-style keyboards);

or

• Use the keyboard shortcut keys Alt/Up arrow or Alt/Down arrow.

Scrolling the display may scroll the command line (including the cursor) off the display, making the cursor disappear. If that happens, the cursor will reappear when the command line is scrolled back onto the display. You can get the command line and the cursor back onto the display at any time by:

• Typing any character on the keyboard (it will appear on the command line);
• Moving the cursor forward or back on the command line; or
• Using the Up or Down arrows to scroll through command history.

In any of the above cases, the display will instantly switch back to the original place, displaying the command line.

Some operations can clear the screen (eg printing a Form Feed character). Since the command line is often at the bottom of the display, such events force all lines of the display above the command line to scroll off the top of the display before the display is cleared. This means that none of the history before the clear operation is lost.

The number of lines of text stored in the text buffer is limited to the maximum defined by the Console Prefs. When that maximum is exceeded, the console device may start to "cull" lines from the text buffer into a disk file (if the Console Prefs allow it). Any lines of history that have been written to the disk file are still accessible by scrolling back through the history, but only a line at a time (Page Up does not work under that condition).

Naturally, if several Shells share a Console window (with or without a ClickTab gadget), each such Shell has its own independent history file.

When the Shell is closed (and the Console preferences allow it), any remaining rows of text on the display will be written out to the history file before it is closed. If the option is selected in the Console Prefs, the file will be saved, otherwise it will be deleted.

The Prefs Options allows you to choose what, if any, history to save when the session is closed.

The saved history file is called "ConsoleTextnnnn", where "nnnn" is a unique serial number identifying the console display. The "nnnn" serial number is incremented and written back to ENVARC: after every new console is opened.

Command line editing

While using the shell you will probably have to move around in the current line and to change some text to fix errors. Here are the keyboard shortcuts you can use to make your work with the shell easier.

• Left-arrow

Moves cursor one character to the left.

• Alt Left-arrow

Moves cursor to the beginning of the current word, or to the beginning of the previous word, or to the beginning of the line.

• Shift Left-arrow, Ctrl A, Home ("PC"-style keyboards only)

Moves cursor to the beginning of the line.

• Right-arrow

Moves cursor one character to the right.

• Alt Right-arrow

Moves cursor to the beginning of the next word, or to the end of the line.

• Shift Right-arrow, Ctrl Z, End ("PC"-style keyboards only)

Moves cursor to the end of the line.

• Backspace

Deletes the character to the left of the cursor. All characters at and to the right of the cursor are shifted one character left to fill in the gap. The cursor moves one character left.

• Alt Backspace

Deletes the whole word to the left of the cursor.

• Delete

Deletes the character under the cursor. All characters to the right of the cursor are shifted one character left to fill in the gap. The cursor does not move.

• Alt Delete

Deletes the whole word to the right of the cursor.

• Ctrl H

Deletes the previous character (same as Backspace).

• Ctrl M

Processes the command line (same as Enter).

• Ctrl J

Adds a line feed.

• Ctrl X

Deletes the current line.

• Ctrl K

Deletes everything from the cursor forward to the end of the line.

• Ctrl Y

Replaces the characters deleted with Ctrl K.

• Ctrl U

Deletes everything from the cursor backward to the start of the line.

Command/Filename completion

Coming soon...