Article 245 of comp.binaries.cbm: From: hab@fimp02.fim.uni-linz.ac.at (Richard Hable) Newsgroups: comp.binaries.cbm Subject: ShadOS/R0 (Part 0/1) 64 Date: 22 Mar 1995 22:25:50 GMT Organization: Gustavus Adolphus College Lines: 377 Approved: mmiller3@gac.edu (comp.binaries.cbm) Message-ID: <3kq85e$kig@news.gac.edu> NNTP-Posting-Host: poblano.gac.edu Originator: mmiller3@poblano ==================================== ShadOS - Release #0 (March 17, 1995) ==================================== The file shados-0.sfx is a self-extracting archive which contains the ShadOS system with a command-line interpreter and some demo modules. It is intended to demonstrate how ShadOS works and what it looks like. There are no real application programs for it yet, When extracting shados-0.sfx by executing it on a C64 or C128, files with the following crc32-code are written to disk: crc32b = d532e9d1 for "shados" crc32b = 648a23bc for "obj.shados" crc32b = 5d30bcf2 for "obj.shell" crc32b = 940a2cd4 for "hlp.shell" crc32b = b482f60d for "obj.out" crc32b = 68ab58bd for "obj.hi1" crc32b = b07e8b92 for "obj.hi2" GENERAL INFORMATION ------------------- ShadOS is intended to be a system with small hardware requirements and good utilization of the C64 operating system. It allows using several applications at the same time. Unlike other systems, applications do not have to consist of single independent executable files that have to be loaded from disk every time they are needed. Instead, programs consist of modules which stay resident in memory and can share common code and data. Modules can supply commands for the user to enter which lead to execution of code. Modules can import other modules, which means that they use code and data provided by other modules. When modules are loaded into memory, imported modules that do not reside in memory yet, have to be loaded too. Then, program code has to be adjusted to the base addresses of the modules in memory, which are not known during creation of the modules. To make all this possible, object files are used which allow dynamic loading and linking of relocatable code. STARTING SHADOS --------------- The system can be loaded and started on a C64 with the following instructions: load"shados",8 run This will load and activate the system and the command-line interpreter (shell). You can then enter commands until you leave ShadOS with either the appropriate shell command or be pressing STOP/RESTORE. As long as the system is still in memory, it can re-started with run1000 To load ShadOS from a device other than 8, the device numbers in lines 120 and 150 of the BASIC loader have to be adapted. ShadOS uses memory between the address it was loaded to and $BFFF. Therefore, it can be used with programs which use memory between $C000 and $CFFF, as for example RAMDOS. USING THE SHELL --------------- The shell allows the user to enter commands to be executed. It recognizes different kinds of symbols: Names consist of a letter followed zero or more letters and digits, for example: abc A12x Strings consist of arbitrary characters within double quotes. With strings at the end of command lines, the second quote may be omitted. Examples: "abc" "" Numerical values between 0 and 65535 may be entered in different forms: decimal digits, hexadecimal digits preceded by "$", binary digits preceded by "%", or a character within single quotes which denotes its PETSCII-code. Examples: 12345 $801 %10101010 'x' A semicolon denotes a comment, which means that it and the rest of the command line will be ignored. Many commands require specifying files to be read or written to. Usually, this is possible by specifying the device number, a secondary address, and a file name. If no device number is given, a default device number will be used. If no secondary address is given, the system will automatically choose one and also modify the file name according to the task to be performed. For example, the following commands use the same parameters: = 8 "abc" = 8 2 "0:abc,s,r" If no file name is specified, an empty name or a default name provided by the command is used. SHELL-COMMANDS -------------- The shell recognizes a number of built-in commands which usually consist of a single character followed by parameters. A short list of these commands is given in file "hlp.shell", which can be displayed within ShadOS by the command: ="hlp.shell" The following gives more detailed explanations and examples: # [dev] When entered without parameter, the default device number is shown on the screen. This number is used when the user specifies files without providing a device number. By using a parameter, the default device number can be changed. # #9 / [dev[sec]] ["wildcard"] Displays the directory of a disk. By specifying a wildcard, files matching a certain pattern can be selected. / /9 /"obj.*" @ [dev[sec]] ["text"] If a string is specified, it is sent to the disk drive as a command and the resulting disk status is displayed. Without a string, the current disk status is shown. This command opens and closes the drive's error channel; therefore, open files on the drive are closed. Note: This command can hang when a non-existing device is accessed. In this case, switch off and on devices on the serial bus until an error message appears; or simply press STOP/RESTORE and restart the system with "run1000". @ @9 @10"s:abc" >[>] [dev[sec]] ["filename"] If a device number or a file name is specified, output re-direction to a sequential file is started. With ">" the file is created, with ">>" data is appended to an existing file. Commands which support output re-direction will write into the file what they would otherwise display on the screen. If output re-direction is already active, the old file is closed before opening the new one. The command without parameters finishes output re-direction. >"newfile" >>9"oldfile" >4 7 > < [dev[sec]] ["filename"] If a device number or file name is specified, input is re-directed. This means that the shell will start reading commands from a sequential file until either another command for input re-direction is read or the end of the file is reached. This way, command lists can be executed. The command without parameters finishes input re-direction. <"commandfile" = [dev[sec]] ["filename"] A textfile is read and displayed. For yet unknown reasons, this does not work with sequential tape files. ="hlp.shell" =10 2 "abc,u,r" ![!] "texts" codes ... Prints text in strings and characters specified by their PETSCII code. An arbitrary number of parameters can be specified in any order. With "!" a carriage return is appended to the text, with "!!" it is omitted. !"Hello World" !34"a string"34 ! !!147 : [modulename ...] If no module names are specified, a list of modules resident in memory is displayed. Otherwise, specified modules which do not reside in memory yet are loaded from the default device. If necessary, other modules required (imported) by them are loaded too. Note that module names, not file names, have to be specified. No quotes or leading "obj." are necessary. : :out :hi1 hi2 ? [modulenames ...] If no module names are specified, a list of commands from all modules resident in memory is displayed. Otherwise, only commands exported by the specified modules are shown. ? ?hi1 hi2 ?? The current status of memory usage is displayed. [modulename.]commandname ... A command exported by a module is executed. These commands may or may not require parameters. If a module name is specified, the appropriate module is loaded before command execution, if necessary. Otherwise, the command must be exported by one of the modules already resident in memory. hi1.say1a say1b . Exit from the shell. This usually gets you back to BASIC. ShadOS can then be re-started with loaded modules still in main memory with "run1000". EXAMPLE MODULES --------------- Three example modules are provided: "out", "hi1", and "hi2". They show how two modules representing application programs ("hi1", "hi2") can share common code provided by another module ("out"). Application programs export commands for the user to execute. Module "out" exports sub-routines for printing text. Modules "hi1" and "hi2" import "out" and call these routines. When executing command "say1a" of module "hi1" with hi1.say1a both "hi1" and "out" are loaded into memory. Later executions of commands exported by "hi1" require no further loading. When, after that, command "say2" of module "hi2" is executed the first time with hi2.say2 module "hi2" is loaded into memory. Module "out" doesn't have to be loaded, since it is already there. The source code of the example modules was translated with a cross-assembler which creates ShadOS object files. Modules can export labels by marking them with "*". Other modules can then use these labels by an "IMPORT" statement. Label declarations of the form "PROC name^" denote commands. MODULE out IMPORT Kernal WriteString* stx 251 / sty 252 ldy #0 .loop lda (251),y beq .end jsr CHROUT iny / bne .loop .end rts WriteLn* lda #13 / jsr CHROUT rts END. MODULE hi1 IMPORT out PROC say1a^ ldx #strA / jsr WriteString jsr WriteLn rts PROC say1b^ ldx #strB / jsr WriteString jsr WriteLn rts strA ascii "Hello world 1a" / byte 0 strB ascii "Hello world 1b" / byte 0 END. MODULE hi2 IMPORT out PROC say2^ ldx #str / jsr WriteString jsr WriteLn rts str ascii "Hello world 2" / byte 0 END. ERROR HANDLING -------------- In case of an error, an error message is printed. If the error was caused by wrong user input, its approximate position within the input line is indicated by an arrow. Input and output re-directions are stopped; however, files on the disk drive may stay open. In this case, enter the command to display the disk status to properly close them. Errors during file access are checked by examining the KERNAL error codes and the status byte values. This catches all errors during sequential reading and writing except errors during closing a file, which are very unlikely. COPYRIGHT: ---------- The programs and instructions were written by Richard Hable. You may distribute them freely. There is no warranty, use them at your own risk! Comments and bug reports are welcome. E-mail: Richard.Hable@jk.uni-linz.ac.at