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 / ldy #>strA / jsr WriteString
                  jsr WriteLn
                  rts
    PROC say1b^
                  ldx #<strB / ldy #>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 / ldy #>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





