UserDoc:Shell

What is a shell?

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. 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 and closing 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.

TODO: insert icon image

• 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.

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 RAmiga-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 RAmiga-< and RAmiga-> 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.

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.

Read the manual of the shell preferences editor

Using a shell

A shell being a text only interface you will use it almost exclusively with the keyboard. There are a few graphic elements that will require the use of a mouse: menu items, window sliders, tabs...

TODO: insert shell image with tabs and menus

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 RAmiga-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 RAmiga-I.

• About...

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

---

• Close shell

This item issues a CLOSEWINDOW command (equivalent to typing Ctrl-\ or RAmiga-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 RAmiga-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 RAmiga-<.

• 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 RAmiga->.

• 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 RAmiga-H or the Help or Scroll Lock keys.

Command line editing

Typing commands in a shell.