
                          SS.Library Example Programs

                                   Release 2

                Written by Martin Mares, MJSoft System Software

================================================================================


Preface
=======

   This directory contains some useful utilities, which use the ss.library.
Assembly source files (#?.asm) are included.

   All files in this archive may be freely distributed and modified without
any restrictions.

   All the utilities require Kickstart 2.04 or higher and the ss.library.

   Everything except NewAlertHook is PURE and can be made RESIDENT.


WHAT'S NEW IN THIS RELEASE:
---------------------------

Inf 1.1 - displaying of unknown filesystem types corrected ; $VER added
NewAlertHook 40.3 - some small bugs removed ; EXEC conditionals added
   for easy inclusion in RAM kickstart.
AsmCheck removed
FSort added
RemDev added


Inf
===

   This small utility is similar to the standard Info command, but displays
much more information about the devices followed by short description of
available memory.

Inf output is divided to nine columns:

Device - name of DOS device (for example DF0:)
  Size - disk size
  Free - free space
  Free - free space in percents of total capacity
  Stat - status - R/W=Read/Write,VAL=Validating,R/O=Read Only
   Err - number of errors detected during disk access
  Type - filesystem type (OFS,FFS,OFSI=OFS INTL,FFSI=FFS INTL,OFSC=OFS DIRC
                          FFSC=FFS DIRC,MSD=MSDOS,MSDD=MSDOS DD)
 Block - block size
Volume - volume name

The device information is followed by summary of Chip, Fast and Slow (C0-RAM)
memory: <RAM name> : <free space> (<largest>) of <total size>.


DVIType
=======

   Analyser of TeX Device Independent output files.

Usage: DVIType <DVI File>

Output syntax: <address> <command> [<parameters>]

For command summary see source text of TeX.


AddModule
=========

   AddModule is able to install resident modules to KickTag and KickMem lists,
which makes them reset-proof.

Syntax: AddModule <ModuleName> [CLASS <class>] [PRI <pri>] [INIT]

ModuleName - name of resident module you want to install
     class - module class 0-127 (see exec/resident.i). The seventh bit cannot
             be overriden
       pri - module priority -128-127

   You may also try to install usual libraries and devices as resident modules.
In this case, specify CLASS 4 and PRI -128. If some library uses some other,
try to arrange the priorities in appropriate order. The ss.library can be
installed by this way.


NewAlertHook
============

   This is a resident module (must be installed by AddModule) replacing
standard alert display mechanism by slightly improved routine, which is
able to show error text and name of process causing the error. The module
itself doesn't require the ss.library.

   Thanks to Brian Gontowski for inspiration (InstallNewAlert). This one
is only 3K long.

   Currently includes all alerts up to those generated by kickstart 3.0.


TwoWindows
==========

   An useless example of asynchronous file I/O. Opens two console windows
labeled "First Window" and "Second Window". Any text written to the first
one is copied to the second one and vice versa. To abort the program,
enter CTRL-\ (EOF) in both windows.


KeyRes
======

   KeyRes is a keymap analyser. It takes a keymap file and disassembles it
to special source file.

Syntax: KeyRes <from> [<to>]

  from - name of keymap to be disassembled. It can be stored in RAM or on
         a disk.
    to - name of file to store the output to. Default is <from>.kms.

Keymap source file is a sequence of key definition blocks, which have the
following syntax:

[<KEY TYPE>] KEY <NAME> [{<QUAL>}] [CAPS]
<followed by several lines of key meanings>

  Key type - can be DEAD, STRING or empty
      Name - key name (described below)
      Qual - qualifiers affecting processing of this key (SHIFT, ALT, CTRL)
      CAPS - set if CAPS LOCK act as SHIFT

Key names:

TILDE, ONE, TWO, THREE, FOUR, FIVE, SIX, SEVEN, EIGHT, NINE, ZERO, MINUS,
EQUAL, BACKSLASH, K0, Q, W, E, R, T, Y, U, I, O, P, LBRACK, RBRACK, K1, K2,
K3, A, S, D, F, G, H, J, K, L, SEMICOLON, APOSTROPHE, HASH, K4, K5, K6,
LESS, Z, X, C, V, B, N, M, COMMA, DOT, SLASH, KDOT, K7, K8, K9, SPACE,
BACKSPACE, TAB, KENTER, ENTER, ESC, DEL, KMINUS, UP, DOWN, RIGHT, LEFT, F1,
F2, F3, F4, F5, F6, F7, F8, F9, F10, KLBRACK, KRBRACK, KSLASH, KASTERISK,
KPLUS, HELP, LSHIFT, RSHIFT, CAPSLOCK, CONTROL, LALT, RALT, LAMIGA, RAMIGA.

Key meaning:

Normal keys		[<QUAL>] '<character>' | <character code>
			   |		|
			   |		*--- character generated by this key
			   |
			   *-- qualifiers of this meaning (SHIFT,ALT,CTRL)
			   |
String keys		[<QUAL>] "<string>"
			   |	     |
			   |	     *--- string generated by this key
			   |			use "" or \" for double quotes
			   |			use \cc for hex. char. code
			   |
			   |
Dead keys		[<QUAL>] '<character>' | <character code>
			   |		|
			   |		*-- code of meaning not affected
			   |		    by prefix (dead) keys
			[<QUAL>] PREFIX <num>
			   |		  |
			   |		  *-- # of prefix generated by this key
			[<QUAL>] PREFIX <p1>,<p2>
			   |   used if prefix has to be pressed twice to get
			   |   some other meaning. In this case, the final
			   |   prefix code is <p1_of_first_prefix> *
			   |   <p2_of_second_prefix> + <p1_of_second_prefix>.
			[<QUAL>] MOD { '<char>' | <code> , ... }
					|
					*-- meaning modified by dead keys
					    contains list of characters -
					    - for each prefix code one char.


KeyComp
=======

   Keymap compiler - does reverse process to KeyRes. Useful for creating
of keymaps in non-interactive way.

Syntax: KeyComp <source> [<dest>]

   source - source file (.kms is appended if there's no extension in it)
     dest - destination file (if omitted, source file name without extension
	    is substituted)


FSort
=====

   Very fast file sorting utility (analogous to C:Sort).

   Speed comparison (280K file, on GVP A530 Turbo - 68EC030 40MHz)

	original C:Sort 37.3	36 seconds	380K used
	ARP Sort		27 seconds	317K used
	FSort			4.9 seconds	334K used

Syntax: FSort [<source> [<dest>]] [CASE]

   source - source file (standard input if omitted)
     dest - destination file (standard output if omitted)
     CASE - perform case-dependent sorting

   Destination identical to source is allowed.


RemDev
======

   Device remover for handler debugging.

Syntax: RemDev <device> [FORCE]

   device - device to be removed
    FORCE - remove even if ACTION_DIE refused.


Final words
===========

   Send bug reports and suggestions to mjsoft@k332.feld.cvut.cz.

