#
Using the textual interface of Oberon

[ Text | Contents | Index | Master index]

# Tutorial objective

Introduce you to the Oberon textual user interface (TUI), the standard system editor, the file system and the system commands. The tutorial runs along the same line as Martin Reiser's User's Guide in The Oberon System on which it is based. Sitting at your workstation you are able to 'look and feel' Oberon and practice immediately new commands.

The tutorial is an application of the Gadgets system: you should organize your display space with, on the left your prefered desktop and on the right the Oberon system track. If your desktop covers the entire display screen, middle click on the [Close] button located in the top left corner and position this tutorial frame on the left, that is in the user track, of the screen for good visibility.

Estimated time: 60 minutes.

# The viewer

One of the intrinsic concepts of the Oberon system is the viewer, a rectangular area on the display. Viewers provide a port to an underlying application which is typically an editor operating on text, picture or graphic data objects. Viewers are non-overlapping and tile the display area completely. This is how it is organised: The screen of your Oberon system is divided vertically into two tracks: a wider user track (on the left) and a narrower system track (on the right).

The vertical stripe of a track is further subdivided horizontally into viewers. Viewers are stacked, one on top of another, and fill tracks from the bottom up without leaving gaps. Within this grid, viewers are opened and closed by issuing commands or under program control. There are two commands for opening text viewers - Edit.Open and System.Open. A log viewer, a specialized text viewer, is opened with System.OpenLog.

## Viewer layout

Open a viewer in the system track by clicking on (this command) System.OpenLog. An Oberon viewer is a rectangular area on the display with two active subframes: a menu frame at the top and main frame below. Now locate the following layout elements in that viewer:

- the title bar with the viewer name at the left followed by by what is called the menu text (a set of commands). The title bar appears on a grey background.
- the vertical scroll bar located on the left
- the main text area below the title bar

The name (here "System.Log") identifies the viewer. In many cases, it corresponds to a file name designating the disk file where the data displayed in the main text area is stored. Close the viewer by clicking on the menu command "System.Close".

## Placement of the viewer

The user has control over the placement of viewers:
o at the time of the open command,
o after the viewers have been opened.

Normally, when an open command is issued, Oberon makes a reasonable guess as to where to place the viewer on the display. That is precisely the difference between the two open commands above: with Edit.Open, the viewer will open in the user track and with System.Open in the system track. The user, however, can indicate where the viewer should open by means of the pointer. Regardless of where Oberon would have opened the viewer, it will open in the track of the pointer and its top edge will be at the height of the pointer.

Verify those assertions by yourself, placing the pointer in any of the user or system tracks and clicking on System.OpenLog. Remove these viewers by clicking on the menu command "System.Close".

An opened viewer may be resized or relocated with its title bar.

# Mouse commands

The Oberon system relies very much on the availability of a mouse. A tutorial Using the mouse and the keyboard has been developed specially for new Oberon users. Summarizing what is presented at length in that tutorial, we might say that the three mouse keys are assigned to the following basic functions:

- Mouse Left key - ML: point i.e. set the caret (mark the insertion point)
- Mouse Middle key - MM: execute a command pointed at by the mouse focus
- Mouse Right key - MR: select (character, word, stretch of text, line, paragraph)

The three keys are used to issue commands whose meaning is defined by the class of the viewer which contains the cursor. When used with the standard system editor - that is with a viewer of the class text viewers, often used functions such as select, copy, delete and execute can be executed "in place" using the mouse alone, without the need for a tool or a menu. The complete set of mouse commands used by the editor is documented below.Cancelling a mouse action: When a wrong key is pressed, pressing all keys cancels any action that would otherwise be initiated. The same holds true for an interclick.

## Cursor in main text area

All edit commands work either on selected text or on the text at the caret location. Oberon ensures that at any time only one caret is set. However there is no unique selection, each frame may have its own selection. Commands working on the selection always work on the most recently made one.

Oberon abandons the notion of a program, atomic actions are called Commands. Commands are executed by pressing and releasing the middle mouse key while pointing at the command name. As visual feedback the command name is underlined while the middle mouse key remains pressed.
Notes:
(1) There are two variants of copy:
Left + middle: Copy an existing selection to the caret.
The caret is set with this interclick.
Right + middle: Make a selection and copy it over to the caret.
The caret must have been set earlier.
(2) Font and color of the text at the caret location are copied.
(3) This interclick is specially useful when developing software.

## Cursor in scroll bar

Notes:
(1) Dragging tracks the line which becomes the topmost line.
(2) Scrolls to the begining of the document or a step up,
depending on the editor used.

## Cursor in title bar

The title bar is also text. All editing operations work the same way as those in the main editable text - new commands may be added, the name may be changed, stretches of text may be selected, deleted and copied. The only restriction is that, in order to set the caret (it is NOT visible), the mouse has to point at the very bottom of the area rendered in reverse video. Also, a changed title CANNOT be saved to disk. When the viewer is reopened, the standard commands are again displayed.
Note:
If the mouse cursor is in the upper part of the title bar, pressing the
left key removes the reverse video, thereby telling the user that a
tracking mode has been entered. Dragging on the left key will
determine the new top position in the track. On releasing the key,
the top edge of the viewer moves to the height of the mouse
cursor and the viewer contents is redrawn.
If the middle key is interclicked while dragging, the viewer may be
relocated in another track.
This interclick can also be used to force a viewer to redraw its
contents.

## Large selection

If a large portion of a document has to be selected, it may not fit into in the viewer. In this case, a second viewer must be opened adjacent to the original one using System.Copy. The text in the second viewer must then be scrolled until the end of the desired selection becomes visible. The large selection can now be made as follows:

(1) Select the beginning of the desired large selection in one viewer. An arbitrary piece of the beginning may be selected - just one character is sufficient.

(2) Select the end of the desired large selection in the other viewer. As before, an arbitrary large piece of the end may be selected. Interclick commands can be given while selecting the tail piece. They operate on the whole large selection.

Now the entire text, including the invisible portion between the beginning of the first and the end of the second sub-selection, is selected.
Note: The entire large selection is NOT highlighted in reverse video. Only the two sub-selections are.

# Taking control of Oberon

Now that you know how your display space is organized, what actions can be started with your mouse and how to point with the cursor to a point where text can be entered, deleted, edited, you are invited to take control of Oberon.In Oberon, the code unit which can be executed from your user interface is called a command. Commands are simply typed into a text viewer and then executed by pointing at them with the mouse cursor and clicking the middle mouse key. A command may be embedded anywhere in a text. If a command produces output to the screen, the output may appear in a viewer already opened or a new text viewer may be opened to present it.

To see an example corresponding to the first case click on this command System.Time . It is a command producing this output text in the System.Log (look at the upper part of the system track):
System.Time dd.mm.yy hh:mm:ss.

To see an example corresponding to the second case click on this command System.ShowModules. It is a command producing an output text in a System.ShowModules viewer which is opened in the system track.

And now click on the 'System.Close' command which appears in the title bar of that viewer.

## Command definition and syntax

An Oberon command is a parameterless procedure in a module written in the programming language Oberon. It is written as: Module.Procedure

where Procedure is the name of a procedure exported by a module named Module. You have just seen three examples of that.

## Parameter

Most commands require parameters. It is important not to confuse these with the formal parameters of procedures written in the programming language Oberon. The parameters of commands have different sources such as:

- text following the command name
- text contained in the selection
- the viewer from which the command is executed
- the marked viewer, i.e. designated by the pointer.

The parameters provided by these sources is text that may be of arbitrarily complex syntax. A single name or a list of names are just the simplest cases. We shall frequently make use of the expression 'parameter list'.

## No parameter

A few commands simply do not require parameters at all. For example, the command System.OpenLog which opens a text viewer named "System.Log". Some commands, also not requiring parameters, operate on implicitely defined object(s). Commands which appear in the title bar usually take their viewer as implied parameter. For example, System.Close, which when executed from the title bar, needs no parameter and closes the viewer. Do close the "System.Log" you have just opened.

## Single name as parameter

Several commands expect a single word after the command's name. That word is separated from the command name by one or several blanks. A word is a string of at most 32 characters not containing blanks. It is usually a file name or a template defined by its own syntax. Oberon uses structured names to identify objects. The syntax of names is:

name = namePart{"."namePart}.
namePart = letter{letter | digit}.
letter = "A" | "B" | ... | "Z" | "a" | "b" | ... |"z".
digit = "0" | "1" | ... | "9".

Thus, if a name is expected, any special symbol terminates the name. For example, System.Open EmptyViewer.Text~. Upper and lower case letters are considered distinct.

The following are examples of structured names:

Oberon3TUI.html the name of a file containing this tutorial and the name of this document: look at its name plate at the top left corner.

Sample.Mod the name of a file containg the source text of the module Sample, written in the Oberon language.

## List of names as parameter - {nameList} ~

Some commands take a list of names as parameters. The list may be of variable length. It is separated from the command name by one or several blanks and items in the list are blank delimited. The list is terminated by a special symbol, typically "~". For example, executing Compiler.Compile M1.Mod M2.Mod M3.Mod~ will compile all three files in that order.

## List of name pairs as parameter - {namePair} ~

A few commands process a list of name pairs as indicated in this example:

System.RenameFiles A.Mod => a.Mod B.Text => b.Text ~

The arrow composed of the character "=" immediately followed by ">" that the file "A.Mod" is being renamed to "a.Mod" and not the other way round.

## Selection as parameter - ^

If "^" follows the command name, the parameter is found in the most recent selection (this upward arrow is the caret on your keyboard). Only an initial portion of a word needs to be selected, but at least the first character.

Re-using a recent example, select a few initial characters in -> EmptyViewer.Text and click on System.Open ^.

Warning! Watch this pitfall: Do not place the selection in the system log viewer. Many commands write to it and as you know the selection may be cleared before this last parameter is processed.

## Marked viewer as parameter - *

Other commands operate on the marked viewer, either implicitely as for example, System.Close executed in the title bar of a viewer, or explicitely by expecting an "*" after the command name as for example Edit.Print LPT1 *. Assuming that the marked viewer's name is "Test.Mod", then the previous command is equivalent to: Edit.Print LPT1 Test.Mod.

# Using the standard editor

Every viewer displaying text (called text frame) embodies an interactive text editor. We can regard it as an interpreter of a set of built-in commands (so-called intrinsic commands, e.g. the mouse commands presented in the previous chapter).Module Edit is a toolbox (see Edit.Tool) of standard editing commands (so-called extrinsic commands).

## Opening a text viewer - Edit.Open

Edit.Open name | ^ opens a text viewer named name and, if a file with the same name exists, displays the file contents in the viewer. Otherwise, an empty viewer is opened. The viewer is opened in the user track unless the pointer is set.
Note: The selection is also searched if the text line is empty after the command name.

Exercises:
Edit.Open Sample1.Mod and close it.
Select a portion or whole of Sample1.Mod .
Edit.Open ^ and close it.
Edit.Open
and close it.

## Showing a string in a module - Edit.Show

Edit.Show module.txt | ^ opens a viewer named module.Mod displaying the module if it exists with the first occurence of the string "txt" positioned near the top. If the module does not exist an empty viewer is opened. The viewer is opened in the user track unless the pointer is set.
Note: The selection is also searched if the text line is empty after the command name.

Exercise:
Edit.Show Examples.InsertAt opens a viewer displaying the source text in the file Examples.Mod.

## Storing a text - Edit.Store

Edit.Store [name | ^] If executed from the title bar, the viewer contents is stored in a disk file whose name is identical to the viewer's name. If executed from a main text, the contents of the marked viewer is stored in a disk file named name. The file is stored in the current directory. If a file with that name already exists, it is renamed: the suffix ".Bak" is appended to its original name.

## Undo last delete - Edit.Recall

Edit.Recall inserts the most recently deleted text at the position of the caret (undo). The caret may be in a different viewer from the one where the text was deleted.

Note: Deletion and Edit.Recall can be used in combination to move text from one place to another (cut and paste).
(1) Delete text to be moved.
(2) Place the caret at the insertion point.
(3) Execute Edit.Recall

Caution: After having deleted the text to be moved, do NOT use the backspace key to correct a typing error, e.g. while typing "Edit.Recall". The deleted text is lost and replaced by the last character deleted.

## Changing the color - Edit.ChangeColor

Edit.ChangeColor colorNumber changes the color of the most recent selection to colorNumber. The parameter must be an integer denoting a color in the color palette.

## Changing the font - Edit.ChangeFont

Edit.ChangeFont fontName changes the font of the most recent selection to fontName. The parameter must specify a valid font name -> System.Directory *.Scn.Fnt .

## Copying the font - Edit.CopyFont

Edit.CopyFont changes the font of the selection to the font at the place of the star-shaped pointer.

## Searching a pattern - Edit.Search

Edit.Search searches a pattern in the marked text. The pattern is defined by the most recent selection. If none exists, the previous pattern is used. Searching is started at the position of the caret. If none exists in the marked text, searching starts at the beginning. The initial value of the pattern is the space character.

Note: Repeated execution of this command searches for subsequent occurrences of the pattern.

## Locating a position - Edit.Locate

Edit.Locate The text in the selection is scanned from left to right for the first occurrence of an integer. Assume that 'n' denotes that integer. The caret is then placed in the text of the marked viewer after the nth character. Carriage return characters are also counted. The command is used for locating a compiler detected error in the (source) text of a module.

## Printing a text - Edit.Print

Edit.Print ServerName [%] { (textFileName | *) ["/" noOfCopies] } sends all texts specified by the parameter list to the print server whose name is taken from the first entry in the parameter list. Names in the parameter list refer to text files, the symbol * to the text in the marked viewer. The special character "%" specifies the vanilla-print option: the texts are printed in a single monospaced small font (Gacha10l). This option is typically used for printing source program listings. The option noOfCopies specifies the desired number of copies. It must be a single-digit number.

On workstations directly connected to a printer ServerName is the name of the printer port (e.g. LPT1 on a PC, or QuickDraw on an Apple Macintosh).

## Clearing a viewer - Edit.Clear

Edit.Clear [*] (Windows ONLY) clears a viewer: if executed from the title bar, it clears the viewer containing the title bar, and if executed from a main text, the marked viewer. The deleted text can be re-inserted after the caret by executing the Edit.Recall command.

## Replacing text - Edit.Replace

Edit.Replace (Windows ONLY) replaces the search pattern set by the last Edit.Search command by the most recent selection and resumes the search of the pattern. The caret must be positioned immediately after the search pattern.

## Replacing all text occurrences - Edit.ReplaceAll

Edit.ReplaceAll (Windows ONLY) replaces the search pattern set by the last Edit.Search command by the most recent selection and proceeds with the search until all occurrences have been replaced. The caret must be positioned immediately after the search pattern.

# Using the file system

Oberon features a simple and extremely efficient file system. The disk directory is organized as a B-Tree. A clear distinction is made between a file and aggregates to access it, which are called riders. Files names are case sensitive and may be up to 32 characters long and contain any number of dots ".". There are no folders or directories, so each file is fully identified by its name. The working files are located either on a hard disk or a RAM disk. Diskettes are primarily used to back-up and restore these working files. Note, that some of the commands described below are not available on MacOberon (see your MacOberon documentation for more information).File name suffixes are normally used to determine the type of data contained in a file. The following suffixes are commonly used:

- Bak: Back-up files; if the contents of a viewer (text editor, graphics editor, ...) are saved (e.g. with Edit.Store) and if a file with the viewer's name already exists, then the old file is kept under the name "name.Bak".

- Fnt: Font file; a font file name usually has the following structure:
<name of font family> <size and attribute> "." <output device> ".Fnt".

Example: Syntax12i.Scn.Fnt - A 12 point italic display font of the Syntax font familiy

- Mod: Oberon module (source program text)
- Obj: Oberon module (object files)
- Pict: picture file
- Text: text file
- Tool: Working menu, which is freely editable (e.g. Backup.Tool)
- Graph or Graphic: graphics document

The facilities for file administration are provided by the command module System.

## Directory management commands

System.CreateDirectory [path]name | ^ creates a subdirectory.

System.ChangeDirectory [path]name | .. | ^ changes the current subdirectory to the one specified.

System.DeleteDirectory [path]name | ^ deletes the specified subdirectory.

System.Directory [template[\d] | ^] opens a viewer named "System.Directory" displaying a list of file names. The names selected are those matching the template, a text string with no blank character, in which the "*" is used as a wildcard - that is, a character matched by any string of non-blank characters. If the option \d follows the template without blanks, the listing includes the date and the time of file creation and file size in bytes. In the case of a ^ following the command name the parameter is taken from the current selection. The viewer is opened in the system track unless the pointer is set.

Examples of templates are as follows:

       String    Files selected
       *          All files
       *.*        All files with a name containing at least two parts, separated by a dot
       *.Mod      All files with suffix "Mod"
       Test.*     All files with first name part "Test"
       *.Scn.*    All files with second name part "Scn"

Exercise: Click here to create a file named "Sample1.Mod".

MODULE Sample1;
IMPORT Oberon, Texts;
VAR W: Texts.Writer;

PROCEDURE Hello*;
BEGIN
Texts.WriteString(W, "hello, world");
Texts.WriteLn(W);
Texts.Append(Oberon.Log, W.buf)
END Hello;

BEGIN
Texts.OpenWriter(W)
END Sample1.

Now be prepared to close the viewer which will open when you click on System.Directory Sample*/d.

## File management commands

System.CopyFiles {name1 => name2} ~ | ^ A list of name pairs name1 and name2 is processed. The pairs are separated by "=>". The file name1 is duplicated and a directory entry name2 is created. If a file name2 already exists, it is overwritten.Exercise: System.CopyFiles Sample1.Mod => Sample2.Mod ~

System.RenameFiles {name1} => name2 ~ | ^ A list of name pairs name1 and name2 is processed. The pairs are separated by "=>". The directory entry name1 is renamed to name2. If a file name2 already exists, it is overwritten.

Exercise: System.RenameFiles Sample1.Mod => Sample3.Mod ~

System.DeleteFiles {name} ~ | ^ deletes all the files named the parameter list.
Caution: Don't forget to terminate the parameter list with a "~". Any file whose name appears after the intended name list will be deleted without a request for confirmation or the possibility of undoing the operation.

Exercise: System.DeleteFiles Sample2.Mod Sample3.Mod ~

# Using a diskette - Native Oberon

Diskettes are primarily used to back-up files of the hard disk. The commands exported by the module Backup serve to:
o format and initialize diskettes
o display the directory of diskettes
o read files from diskette to hard disk
o write files from hard disk to diskette
o delete files from disketteA Backup tool presents a set of commands ready for execution with the mouse.

## Selecting a diskette drive - Backup.SetDriveA

Backup.SetDriveA and Backup.SetDriveB select the (3.5" diskette) drive to be used by the various Backup commands. Default is drive A.

## Formatting a diskette - Backup.Format

Any diskette formatted with a standard DOS formatter may be used. Alternatively, the following commands are provided:

Backup.Format [/D] | /H formats a 2-sided double density (DD) or respectively a high density (HD) diskette in the selected drive. In both cases the diskette has the proprietary Oberon format.

## Initializing in DOS format - Backup.InitDOS

Backup.InitDOS [volName] initializes a formatted diskette, i.e. creates a DOS directory, and sets a volume label. volName must be a valid DOS name (fname.ftype). During this process, all existing data is erased from the diskette. This is much faster than Backup.Format and corresponds to a DOS FORMAT d:/Q/V command.

## Initializing in Oberon format - Backup.InitOberon

Backup.InitOberon [volName] initializes a formatted diskette i.e. creates an Oberon directory, and sets a volume label. volName must be a name or any string enclosed in quotes. During this process, all existing data is erased from the diskette. This is much faster than Backup.Format.

## Viewing the contents of a diskette - Backup.Directory

Backup.Directory[\d] opens a text viewer named "Backup.Directory" displaying the directory of the diskette in the selected drive. If the option \d follows the command without blanks, the listing includes the date and the time of file creation and the file size in bytes. The viewer is opened in the system track unless the pointer is set.

For an empty formatted diskette the following information is displayed:
DD - 720KB after formatting free 112 entries/ 713 KB
after initializing free 111 entries/ 713 KB
HD - 1.44MB after formatting free 223 entries/ 1423 KB
after initializing free 222 entries/ 1423 KB

## Reading all files from a diskette - Backup.ReadAll

Backup.ReadAll copies all files from the diskette in the selected drive to the hard disk.
Caution: If a file name on the diskette matches a file name on the disk, that file is overwritten.

## Reading files from diskette - Backup.ReadFiles

Backup.ReadFiles {name} ~ | ^ reads all files specified by the parameter list from the diskette in the selected drive to the hard disk.
Caution: If a file name on the diskette matches a file name on the disk, that file is overwritten.

## Writing files to diskette - Backup.WriteFiles

Backup.WriteFiles {name} ~ | ^ writes all files specified by the parameter list to the diskette in the selected drive.
Caution: If a file name on the disk matches a file name on diskette, that file is overwritten.

## Deleting files from diskette - Backup.DeleteFiles

Backup.DeleteFiles {name} ~ | ^ deletes all files specified by the parameter list from the diskette in the selected drive.
Caution: Don't forget to terminate the parameter list with a "~".

## Using a DOS formatted diskette

The diskette format used by the Oberon system is close to the DOS format. Full compatibility may be achieved through two commands exported by module System.

### Importing from DOS - System.CopyFromDOS (obsolete)

The directory of a DOS diskette is modified to be readable by an Oberon system.

### Exporting to DOS - System.CopyToDOS (obsolete)

The directory of an Oberon diskette is modified to be compatible with the DOS format.

Caution: File names may be changed (capitalized and truncated).

# Using a diskette - Oberon for Windows

Diskettes are primarily used to back-up files of the hard disk. The commands exported by the command module DOSBackup serve to:
o initialize diskettes
o display the directory of diskettes
o read files from diskette to hard disk
o write files from hard disk to diskette
o delete files from disketteA DOSBackup tool presents a set of commands ready for execution with the mouse.

DOSBackup is the backup utility for Oberon for Windows. It maintains on diskette an extra file _TRANS.TBL containing a translation table of Oberon long names to DOS names.

Macintosh Note:

You can only use this tool on your Macintosh if you installed MacOS 7.5 or any tool that extends you computer with the capability of reading MSDOS diskettes (e.g. PC Exchange).

## Initializing a diskette - DOSBackup.Init

Any diskette formatted with a standard DOS formatter may be used.

Backup.Init erases all the Oberon files and the translation table file on the diskette in the selected drive. Note that all the other DOS files stored on the diskette are not affected.

## Viewing the contents of a diskette - DOSBackup.Directory

DOSBackup.Directory opens a viewer named "A:/*" displaying the directory of the diskette. The listing shows the Oberon files with their long file names based on the information stored in the translation table. The viewer is opened in the user track unless the pointer is set.

## File management commands

DOSBackup.ReadAll copies all files from the diskette to the hard disk.
Caution: If a file name on the diskette matches a file name on the disk, that file is overwritten.

DOSBackup.ReadFiles {name} ~ | ^ reads all files specified by the parameter list from the diskette to the hard disk.
Caution: If a file name on the diskette matches a file name on the disk, that file is overwritten.

DOSBackup.WriteFiles [%] {name} ~ | ^ writes all files specified by the parameter list to the diskette and updates the translation table file. If the option % is used, the files are compressed (using the LZW compression algorithm). Compressed files have a special header that is recognized by the commands ReadFiles and ReadAll; that is, no option is required by these commands.
Caution: If a file name on the disk matches a file name on diskette, that file is overwritten.

DOSBackup.DeleteFiles {name} ~ | ^ deletes all files specified by the parameter list from the diskette and updates the translation table file.
Caution: Do not forget to terminate the parameter list with a "~".

# System commands

The command module System provides the following facilities:

- file administration
- open documents (i.e. document viewers) and the Oberon log
- close, copy and enlarge viewers and tracks, recall previously closed viewers
- display system state information
- unload modules and force garbage collection

## Controlling the viewers in the tracks

System.Open name | [^] opens a text viewer named name and, if a file with the same name exists, displays the file contents in the viewer. Otherwise the viewer is empty. The viewer is opened in the system track unless the pointer is set.
Note: The selection is also searched if the text line is empty after the command name.

System.Copy opens a copy of the viewer in which System.Copy is executed (from the title bar or from the main text). The copy displays the same data as the original viewer. Almost exclusively used from the title bar. The command that makes a large selection possible. But, click here System.Copy you will be surprised! You now have cloned your desktop: whatever you do in one is reflected in the other. Please middle click on the "Close" button under "Oberon.Desk" to remove the copy.

System.Grow enlarges the viewer in which the command is executed (from the title bar or from the main text). An overlay track is opened and the viewer grows to cover the whole track or, if applied to a viewer already filling a track, to cover the whole display. The enlarged viewer displays the same data as the original one.

In the overlay track, other viewers may open and close in the usual manner. If the last viewer in the overlay track closes, the underlying track is restored.
System.Close removes a viewer from the display: if executed from the title bar, it removes the viewer containing the title bar, and if executed from a main text, the marked viewer. The viewer adjacent (on top) to the one which is closed reclaims the freed display area. If the track is an overlay, the underlying track is recovered.

Note: The viewer's contents are NOT saved to disk. If the viewer is erroneously closed before saving to disk (Store), data may be permanently lost, but the viewer may be reopened with System.Recall.

## Controlling the Oberon log

System.OpenLog opens a text viewer named "System.Log" displaying the system-wide log. It is a copy of an existing one. The log is updated regardless of its visibility. Therefore, the log always shows the complete history of the current session. The viewer is opened in the system track unless the pointer is set.

System.ClearLog clears the contents of the Oberon log, regardless of its visibility.

## Reopening the viewer closed last - System.Recall

System.Recall reopens the most recently (perhaps erroneously) closed viewer. This command is very useful to recover data lost through inadvertent use of the command System.Close.

## Closing a track - System.CloseTrack

System.CloseTrack closes the marked track, i.e. removes all viewers in this track. If the track is an overlay, the underlying track is recovered.

## Displaying / setting time and date - System.Time

System.Time [dd mm yy hh mm ss} If the command has no parameter, for example if it is followed by a special symbol System.Time~, then the date and time are displayed in the system log. With parameters, date and time are set. The symbols dd, mm, yy, hh, mm, and ss are all two-digit blank delimited numbers denoting day, month, year, hour, minute and second of date and time to be set.

## Displaying free memory space - System.Watch

System.Watch displays the amount of free main memory space (in bytes) in the log.

## Initiating a garbage collection - System.Collect

System.Collect initiates a subsequent garbage collection.

## Unloading modules - System.Free

System.Free {moduleName[*]} ~ | ^ unloads every module specified by the parameter list. If a module name is immediately followed by "*", imported modules are also unloaded as far as possible. A module can only be unloaded if it has no client; that is, if it is not imported by another module which is still loaded. Therefore, the order of the module names in the parameter list may be significant. The command Builder.Free offers more comfort.

## Freeing libraries - System.FreeLibraries

System.FreeLibraries {libName} ~ | ^ frees shared libraries from memory. This is mostly a harmless operation, since the libraries will simply be loaded again when required. The garbage collector frees libraries automatically when they are not required anymore.

## Show commands exported by a module - System.ShowCommands

System.ShowCommands moduleName | ^ opens a viewer named "System.ShowCommands" displaying a list of all the commands exported by the named module. If the module is not already loaded, it is automatically loaded.

## Show loaded libraries - System.ShowLibraries

System.ShowLibraries opens a viewer named "System.Showlibraries" displaying a list of the currently loaded libraries.

## Displaying loaded modules - System.ShowModules

System.ShowModules opens a viewer named "System.ShowModules" displaying a map of all currently loaded modules. The state of any particular module can be obtained with the 'System.State' command.

## Displaying the active tasks - System.ShowTasks

System.ShowTasks opens a viewer named "System.ShowTasks" displaying a map of all currently active tasks.

## Displaying a module's state - System.State

System.State moduleName | ^ opens a viewer named "System.State" displaying the global data of the named module if it is loaded: all scalar variables and strings together with their values are listed in alphabetical order. If not, the viewer's text is:
moduleName not loaded

The Internet tools use the module 'NetSystem' which is controlled by a section of the oberon.ini file. Issue the command 'System.State NetSystem' to verify its presence.

## Controlling the global text attributes

System.SetFont fontName | ^ applies the font specified by the parameter to subsequently typed characters. The parameter must specify a valid font name.

System.SetColor colorNumber | ^ applies the color specified by the parameter to subsequently typed characters. The parameter must be an integer denoting a color in the color palette.

System.SetOffset offsetNumber | ^ applies the vertical offset specified by the parameter to subsequently typed characters. The parameter must be an integer designating the vertical character offset.

# The Registry

Oberon for Windows has a mechanism to store configuration data permanently. The permanent storage is called the registry. The registry is structured hierarchically into sections and keys. Each section can be thought of as a dictionary that associates a value with a key. Module Registry provides a program interface to the registry (see below). The user interface is embodied in the commands System.Set and System.Get.

System.Set ^ | section key := [ value ] enter a section and key in the registry and associate a value with it. If a value is not given, the entry for the given section and key is removed from the registry. Section, key, and value may be either names or strings.

System.Get ^ | section [ key ] inspect the value of a given section and key in the registry. If a key is not given, all keys contained in the section are listed together with their associated values. Section and key may be either names or strings.

# What's next?

Proceed with the study of the Oberon System 3 graphical user interface (GUI) named Gadgets, starting with the tutorial Introduction to Gadgets.

Revised, afi 11 Dec 1996
Installed on 14 Feb 1997