MShell Documentation
-----------------------------------------------------------------------------
--------- MShell 01.00.2R - The Ultimate OS-9 System Manager ---------
------------------------------------------------------------------------------
This release of MShell is basically the MShell OS9 File Manager. Eventually, I hope to make the MShell series much more than a file manager, but the file management functions were needed for just about any other type of utility program.
Here is a list of some of the unique features of MShell which I have not found in many other Coco OS9 programs.
- CPU identification - Identifies the presence of 6809 or 6309 CPU.
- RBF Drive System Enumeration - MShell automatically recognizes and enumerates all RBF drives on your system.
- User Definable Default Directories - The user can define where the system, commands and temp directory reside. The "Config Utility" allows you to set the directories MShell uses for system files.
- RSDOS File Transfer - MShell will copy and delete files from ANY RSDOS file system including RSDOS partitions on hard drivee and VHDs (virtual hard drive images)
- PC File Transfer - MShell will copy files from your DriveWire4 host PC's drives to OS-9 or RSDOS formatted drives. Your PC's directory entries are listed in a panel in the same manner as the OS9 directories and can be scrolled and selected. You can also copy OS9 files to you DW4 host PC's drives.
- Dual 2 Column Display - MShell utilizes the 640x200, 2 color GFX screen for clean, uncluttered, dual panel, 2 colomn display that displays 42 files of each of 2 directories at once. A total of 84 files displayed on 1 screen. Each panel is independantly scrollable and any file in either directory can be seleted for copying or deletion. Any directory can be select for opening. Each directory listing is independant of the other and can be a completely different drive and file system. You can have an OS9 directory from your HD in one panel and an RSDOS floppy disk in the other. Any file in either directory can be deleted or copied to the opposite panel/dir.
- Virtual Memory Buffers - MShell utilizes OS9 get/put buffers for directory listings and data transfer such as copying files. The virtual memory system in based on the v-mem system used in Ultimuse3 by Michael Knudsen. The v-mem system has been expanded greatly and has many capabilities.
- Fragged Subroutines - MShell also utilizes Mike Knudsen's "fragged subs" system from Ultimuse3. This system allows 8k subroutines to be moved in and out of the main's workspace while sharing the global variables and the ability to call functions as if it were part of the main. This allow almost unlimited expansion to the system just by creating a new fragged subroutine.
- User Defined Screen Colors - MShell's screen colors can be accessed from the "Options" menu. You can set the colors to any of the Coco 3's color set. This setting is saved in the config file.
- Internet Updater - MShell's "Internet Updater" is a one-of-a-kind feature only found in software from "The Barn Studios". DriveWire4 is required for the "Updater" as well as Internet access on the DW4 PC server.
- Bell/Click - A much better "bell" sound as well as a "click" sound used for notices & warnings. The sounds can be turned on or off and the on/off setting is saved in the config file.
- Autoconfig - The autoconfig can be turned on or off. Turning the autoconfig on will save all current settings (including screen colors, mouse preferences, default dirs etc,) when the program terminates.
Now I will list the actual functions of MShell:
- OS9 File Stats - Displays the file descriptor info for any OS9 file.
- OS9 File Copy - Copy any OS9 file to/from ANY file system shown in the opposite panel. MShell will even copy OS9 files to RSDOS or PC file systems.
- OS9 File Delete - Delete any OS9 file from any OS9 file system.
- OS9 File Move - Moves selected OS9 file to opposite panel (OS9 or RSDOS) and deletes the original.
- OS9 Directory Creation - Create a new OS9 directory on any OS9 drive.
- RSDOS File Stats - Displays the file type, mode and size for any RSDOS file system.
- RSDOS File Copy - Copies RSDOS files from one panel to the other. This includes moving RSDOS files to OS9 file systems.
- RSDOS File Delete - Delete any RSDOS file from ANY RSDOS file system.
- RSDOS File Move - Moves selected RSDOS file to opposite panel (RSDOS or OS9) and deletes the original.
- PC Directories - MShell will now view PC directorie via the DW4 server.
- PC File Stats - Displays a few stats for a PC file entry
- PC File Copy - Copies PC files to an OS9 file system
- Mount VHD/DSK files - This function (in PC Dir mode) will mount a .vhd, .dsk, or .os9 file in a DriveWire4 sever disk slot (selectable from 0-3)
- File Search - MShell can search through ANY Coco file system displayed and take you directly to the desired file. Any string (up to 29 characters) can be searched. Wildcards are automatic and the search function will find the string in any position in the target.
- Internet Updater - Updates MShell from the MShell FTP update site on the internet.
I hope to be adding many more features soon.
All functions (but one or two) are accessable with either the mouse or cmd-key combos.
Below is a list of , system rquirements, general instructions and the cmd-keys and their functions.
The instructions for mouse/joystick usage can be found after the Cmd-Key list.
You may want to print these pages as they contain the "Cmd-Key" structure used in MShell.
System requirements for MShell
REQUIRED
- Coco 3 (Or any Coco 3 emulator running NitrOS9) (NOTE: MShell will not function properly in Vcc 1.4.3b in fullscreen mode due to an error in Vcc's mouse routine, use "maximize screen" instead. It will work with keyboard commands if full screen.)
- MShell works with 6809 or 6309 CPU machines.
- 512k - 2-meg of memory (512k min). MShell will utilize any extra memory over 512k automatically.
- OS-9 (KD patched GrfDrv) or NitrOS9
- Must have "CoWin" or "CoGrf" installed in the bootfile
- Must have "pipe", "piper", & "pipeman" installed
- To use the DW4 features, you must have the "scdwv" driver and at least 2 "/Nx" descriptors. You will also need "scdwp" and "/p" in your boot. (all of these are standard in NitrOS9 "latest build" downloads)
- There is also a possibility that the DW4 features (Update, Midi Device, & Midi Profile) will only work on a full NitrOS9 L2 v3.3.0 setup
OPTIONAL
- Joystick or Mouse
- Tandy Hi-Res Interface
- DriveWire4
- Internet Connection (with drivewire4 server)
- RGB Monitor (if using a Coco 3 emulator, RGB delivers the best display)
To install MShell:
Copy all file in the "CMDS" directory on the disk to your "/DD/CMDS" directory.
Copy all files in the "SYS" directory on the disk to your "/DD/SYS" directory.
***** IMPORTANT WARNINGS AND NOTICES *****
WARNING: The MShell "PC File Directory" and "PC File Copy" routines will not work on a Linux DW4 server file system. These function do however work on Windows and Mac DW4 file systems. This is being investigated.
WARNING: When using "OS9 to PC" copies, your DriveWire4 server's virtual printer MUST be set to "Text Mode" and NOT "FX80 Mode". MShell uses DW4's "raw" text print ability to "copy" an OS9 file to the DW4 server PC's hard drive. If your virtual printer is set to "FX80", a "graphic image" of the file will be saved and not the file itself. So to use the "OS9 to PC" copies, please set DW4's virtual printer to "Text".
WARNING: If you are installing MShell over a previous installation of MShell, please delete the "Ms1.init" file found in the "/DD/CMDS" directory. This file may conflict with previous versions of MShell and cause initiallization of MShell to be unstable.
NOTE: MShell is no longer "hard coded" to use the "/DD/CMDS" & "/DD/SYS" dirs. I have fixed this by making all "system" directories user definable. This should make MShell more flexible for all OS9 configurtions.
Also, MShell is meant to be run from a Hard Drive or VHD and will most likely not function well (or very limited) from a floppy drive of any sort (real or emulated).
NOTE: When copying RSDOS or PC files to OS9, any filename with "illegal" characters will NOT copy. It will "seem" to copy, but fails with no notice. I hope to implement a "Save As" feature for these files in the future, but for now, you must rename the files to "legal" filenames from RSDOS or or the PC respectively. Filenames in OS9 CANNOT contain
<spaces>
or the
'";:,<>[]{}!@#$%^&*()=+?/\
characters.
OS9 filenames can only contain Alpha-Numeric characters and use only the symbols "-_."
*** Running MShell from the OS9 command line ***
To run MShell, type:
mshell& <enter>
If the '&' is not included in the command, the calling window will lock until MShell exits. The '&' returns the shell back to the window.
Default screen panel listings are:
Left Panel - Your current dir
Right Panel - /DD/CMDS (or your defined CMDS dir)
Deafult system settings are:
Joystick Port - Right
Hi-Res Interface - No
Bell On - Yes
Autisave Defaults - Yes
** IMPORTANT NOTES:
If when you first run MShell and find you have no mouse cursor movement, from the main screen, hit 'o' to bring up the "Options" menu. Hit 'l' (L) to switch for right/left joystick ports. If you are using the Tandy Hi-Res interface, hit 'h' to activate it. If the warning "bell" annoys you as much as it does me, it can be turned off by hitting 'b'. Screen colors can be changed to suit your eyes by hitting 's' to get to the Color menu. To save these settings as your system defaults, while in the Options menu, hit 'f' or click "File Default Options". This will save the defaults so that MShell will use these settings each time it is run.. Defaults can also be saved by (from the main screen) clicking "File" (or hit 'f'), and clicking "Save defaults" (or hit 's'). If these defaults are not saved, MShell will revert back to the original defaults on the next run of the program. A "Configuration utility" should run on your first run of MShell enabling you to set all these properties.
*** Reading RSDOS partitions on a hard drive or VHD ***
To view RSDOS listings on RSDOS disks, DW4 (or other) RSDOS partitions, you must create a file in /DD/SYS named "hrs_data" formated as below. Use your favorite editor or BUILD to create the file. The file must include all hard drives in the system, including /dd if it is a hard drive. Drive order in the file is unimportant.
Format: drive name [space(s)] [#]RGB_offset
# is required
Obtain the offset value by running Robert Gault's RSDOS program SPECS.BAS for each hard drive in the system. SPECS.BAS is of course used under RGB-DOS/HDB-DOS.
Typical hrs_data file
/dd #368640 (standard Vcc "dual partition" size on most VHDs)
/h0 #368640
/h2 #268380 (possibly the offset used by Cloud9's SuperIDE)
/x0 #368640
/x1 #368640
/x2 #368640
/x3 #368640
The value shown is the size of the OS9 Partition "before" the RSDOS partition.
Without this file in /dd/sys, you cannot read RSDOS partitions on HDBDOS/RGBDOS drives. You can however, read single "disk images (.dsk)" in DW4 slots and real floppy drives as they have an offset of 0. I have provided an example of this file in the SYS dir of the installation disk. It will contain the offsets for the VCC style drives on all HD drivers. You'll have to edit this file to fit your drives.
*** MSHELL COMMAND KEYS ***
While in a "main" menu, you can now use the left and right arrows to move previous and next menus. Menus are accessed by clicking the Menu name or typing the 1st letter of the Menu name.
Main Menu Bar: (working)
[f] - File Menu (working)
[s] - Save Defaults (working)
[r] - Restore Defaults (working)
[q] - Quit to OS9 (working)
[enter] - Exit Menu (working)
[l-arrow] - previous menu (working)
[r-arrow] - next menu (working)
[d] - Drive Menu (working, but soon to disappear as it's part of something else)
[a-z] - Select Drive in Current Panel (working)
NOTE: The "Select Drive" feature reads the selected drive in the panel's current format. To change formats, use the "Panel Options"
menu below instead. It is the only way to view other formats.
[enter] - Exit Menu (working)
[l-arrow] - previous menu (working)
[r-arrow] - next menu (working)
[e] - Edit N/A
[v] - View N/A
[o] - Option Menu (working)
[s] - Change Screen Colors (working)
[m] - Turn the mouse/joystick on/off (working)
[h] - Hi-Res Joystick Interface on/off (working)
[l] - Left/Right Mouse/Joystick (working)
[b] - Bell on/off (working)
[a] - Autosave the Defaults on Exit on/off (working)
[e] - Set Default System Dirs (working)
[d] - Set DW4 Midi Device (disabled for now)
[p] - Set DW4 Midi Profile (disabled for now)
[f] - File Defaults (working) (same as "Save Defaults" in "File" menu)
[r] - Restore Defaults (working) (same as "Restore Defaults" in File menu)
[/ or ?] - System Status Info (working)
[enter] - Exit Menu (working)
[l-arrow] - previous menu (working)
[r-arrow] - next menu (working)
[t] - Tools N/A
The 'Tools' menu will eventually contain useful tools such as:
"Free Memory"
"Free Drive Space"
"Sort Directory"
"View System Stats"
[s] - Search (working)
Search will now search for up to 29 chars in the current panel/dir and once found, will auto-scroll to the selection. Wild card chars are
automatic, just input a partial search string.
[m] - Module N/A
The 'Module' menu will contain the "runnable" modules available through the MShell system. As of yet, no modules are available.
[u] - Utils (working)
[s] - Screen Redraw (working)
[9] - Os9 Shell Prompt (working)
[/ or ?] - System Status Info (working)
[u] - Update MShell (via DW4 internet) (working)
[q] - Quit (working)
[enter] - Exit Menu (working)
[l-arrow] - previous menu (working)
[r-arrow] - next menu (working)
[h] - Help N/A
[enter] - Exits the help screen
Left and Right Panel Actions:
[up Arrow] - Scroll up listing (working)
[Down Arrow] - Scroll down listing (working)
[Shift-Up Arrow] - Scroll up to next page (working)
[Shift Down Arrow] - Scroll down to next page (working)
[Shift-Left Arrow] - Make the left panel the active panel (working)
[Shift-Right Arrow] - Make the right panel the active panel (working)
[,] - Activate Left Panel Options Menu (working)
[ .] - Activate Right Panel Options Menu (working)
[o] - Set OS9 dir mode (working)
[e] - Set DECB dir mode (working)
[p] - Set PC dir mode (working)
[d] - Change Drive (working)
[c] - Change Directory N/A
[r] - Refresh Directory N/A
[n] - Rename Directory N/A
[m] - Make Directory (OS9 only) (working)
[l] - Delete Directory N/A
[enter] - Exit Menu
[<] - (In RSDOS view only) Move to previous partition on RSDOS drive (working)
[>] - (In RSDOS view only) Move to next partition on RSDOS drive (working)
[enter] - On file selection invokes the context menu for selected file
File Context Menu (if File is a program)
The file context menu has been revised for each file system (OS9, RSDOS, PC) to reveal only the options available to that system format.
[s] - Select File N/A
[r] - Rename File N/A
[c] - Copy File (will copy RSDOS to OS9, OS9 to RSDOS, OS9 to OS9, PC to OS9, and OS9 to PC) (working)
[m] - Move File (Same as Copy above but deletes original file. OS9 and RSDOS only) (working)
(Prompts for file copy and file delete in case you decide not to copy or delete the original)
[d] - Delete File (will delete from OS9 & RSDOS drives) (working)
[f] - File Stats (working)
[enter] - Exit Menu (working)
Dir Context Menu (OS9) (if File is a Directory) In PC & OS9 dirs, hitting <ENTER> or double clicking a directory name will open the directory with no prompt or menu. Also, holding down the mouse button on an OS9 dir will open the context dir menu. This action is duplicated by using the 'c' key.
[o] - Open Selected Directory (working)
[s] - Select Directory (OS9 Only) N/A
[a] - Make New Directory (OS9 Only) (working)
[r] - Rename Directory (OS9 only) N/A
[c] - Copy Directory (OS9 only) N/A
[m] - Move Directory (OS9 only) N/A
[d] - Delete Directory (OS9 only) N/A
[enter] - Exit Menu (working)
Mouse Actions: (working)
Clicking any "Menu" or menu item has same results as the key codes.
Clicking anywhere in a non-active panel, activates that panel.
To select a file in the active panel with the mouse, just click it.
Click a selected file a 2nd time calls the "Context Menu" for that file with the exeption of directory files. Clicked directory entries will open that directory. To get the directory context menu, you hold the mouse button down for a couple of seconds.
Click the ^ and v in the panel corners to scroll the active panel by one page up or down.
In RSDOS listings, click the < and > on each side of the "Directory Bar" to move to the prev/next disck on a mutli-partitioned RSDOS hard drive.
Clicking the directory name in the Directory Bar activates the "Panel Options" menu for that directory/panel.
There may be some I've forgotten
NOTES:
MShell 01.00.2s is only a BETA Demo. It by no means represents the final software suite. It is for testing current features only.
Sometimes I add new features daily, other times I spend weeks chasing bugs.
As new features are developed, MShell can be "updated" using DriveWire4 as long as the DW4 server host (your PC) is currently connected to the internet.
To use this feature, from the main screen of MShell, click "Utils" (or hit 'u') then click "Update mshell" (hit 'u' again). Follow the prompts and MShell will check the "Update FTP" for any available updates and display what's available.
You will then be asked if you want to update MShell. Clicking "Yes" (or hitting 'y') will start the download process. Once the downloads have finished, You will need to restart MShell. If MShell is not restarted at this point, it will most likely crash if you continue to run it.
There are still quite a few bugs and most error traps have not yet been implemented, so if MShell crashes or does something strange, take note of what you were doing, what menu system you were in, and most of all, what MShell did as a result of the action. Then send the bug report to me.
All suggestions, bug, and crash reports are appreciated :-)
I can be contacted at:
ooogalapasooo@aol.com
Or on the Coco Mail list on maltedmedia.
Enjoy :-)
Bill Pierce