Editing SmartBox OS

== Changelog ==

 <nowiki>bob	071	Fixed MotorForward bug (%10)
bob	072	CallOS 14 now checks current adc.owner status
jim	072.d1	* Rewrite for new hardware/processor *
jim	072.d1	Moved vectors/workspace to &440
jim	072.d1	Moved rs.inp.buf to &500
jim	072.d1	Moved jobout.buf to &600
jim	072.d1	Moved jobin.buf to &680
jim	072.d1	Moved jobs.status to &700
jim	072.d1	Added irq.X (&A4)
jim	072.d1	Added irq.Y (&A5)
jim	072.d1	Removed short detection code
jim	072.d1	Voided CallOS' 6,7,8,9,10,11,13,16,17,18,19
jim	072.d1	Removed JobCalls ReadADCReg,WriteADCReg
jim	072.d1	Removed JobCalls ReadACIAReg,WriteACIAReg
jim	072.d1	Removed JobCalls ReadVIAReg,WriteVIAReg,SetVIAHigh,SetVIALow
jim	072.d1	Added CallOS 21 Write Outputs
jim	072.d1	Added CallOS 22 Read Outputs added
jim	072.d1	Added CallOS 23 Read Inputs added
jim	072.d1	Added CallOS 24 Write Motors
jim	072.d1	Added CallOS 25 Read Motors
jim	072.d1	Added CallOS 26 Read Keypad
jim	072.d1	Expanded CallOS 5 information
jim	072.d1	Added JobCall IdentSystem to return CallOS 5 info
jim	072.d1	JobCalls now use appropriate CallOS'
jim	072.d1	OS.READBYTE no longer preserves A on CS
jim	072.d1	irq.vec,irq2.vec,nmi.vec now redundant
jim	072.d1	Renamed JobCall DownloadData to DownloadData38
jim	072.d1	Renamed JobCall UploadData to UploadData38
jim	072.d1	Renamed JobCall ExecuteCode to ExecuteCode38
jim	072.d1	Renamed JobCall ReadByte to ReadByte38
jim	072.d1	Renamed JobCall StoreByte to StoreByte38
jim	072.d1	JobCall ForcedADCRead now checks adc.owner first
jim	072.d3	Added CallOS 27 Write printer
jim	072.d3	Added CallOS 28 Read printer
jim	072.d3	Added CallOS 29 Write RTC Reg
jim	072.d3	Added CallOS 30 Read RTC Reg
jim	072.d3	Added CallOS 31 Write RTC string
jim	072.d3	Added CallOS 32 Read RTC string
jim	072.d3	Added CallOS 33 Write RTC bcd
jim	072.d3	Added CallOS 34 Read RTC bcd
jim	072.d3	Added CallOS 35 Write LCD Reg
jim	072.d3	Added CallOS 36 Read LCD Reg
jim	072.d3	Added JobCall WritePrinter
jim	072.d3	Added JobCall ReadPrinter
jim	072.d3	Added JobCall PrintChar
jim	072.d3	Added JobCall PrintStreamZ
jim	072.d3	Added JobCall PrintStream
jim	072.d3	Added JobCall PrintServer
jim	072.d3	Added JobCall WriteRTCReg
jim	072.d3	Added JobCall ReadRTCReg
jim	072.d3	Added JobCall WriteRTC
jim	072.d3	Added JobCall ReadRTC
jim	072.d3	Added JobCall WriteRTCbcd
jim	072.d3	Added JobCall ReadRTCbcd
jim	072.d3	Added JobCall WriteLCDReg
jim	072.d3	Added JobCall ReadLCDReg
jim	072.d3	Added CallOS 37 Write Power ctrl
jim	072.d3	Added CallOS 38 Read Power ctrl
jim	072.d3	Implemented OS.PRINTER
jim	072.d3	Added JobCall PatchMF (MotorForward)
jim	072.d3	Changed irq.vec to int0.vec
jim	072.d3	Changed irq2.vec to int1.vec
jim	072.d3	Added int2irq.vec (wrksp+&20)
jim	072.d3	Added int3irq.vec (wrksp+&22)
jim	072.d3	Added int4irq.vec (wrksp+&24)
jim	072.d3	Added c0irq.vec (wrksp+&26)
jim	072.d3	Added c1irq.vec (wrksp+&28)
jim	072.d3	Added t1irq.vec (wrksp+&2A)
jim	072.d3	Added t2irq.vec (wrksp+&2C)
jim	072.d3	Added txirq.vec (wrksp+&2E)
jim	072.d3	Added tyirq.vec (wrksp+&30)
jim	072.d3	Added s1rirq.vec (wrksp+&32)
jim	072.d3	Added s1rirq.vec (wrksp+&34)
jim	072.d3	Added s2irq.vec (wrksp+&36)
jim	072.d3	Added adcirq.vec (wrksp+&38)
jim	072.d3	Renamed JobCall DownloadData38 to DownloadData740
jim	072.d3	Renamed JobCall UploadData38 to UploadData740
jim	072.d3	Renamed JobCall ExecuteCode38 to ExecuteCode740
jim	072.d3	Renamed JobCall ReadByte38 to ReadByte740
jim	072.d3	Renamed JobCall StoreByte38 to StoreByte740
jim	072.d4	Hardware update
jim	072.d4	Re-assigned CallOS 37 to Write Power/Charge control
jim	072.d4	Re-assigned CallOS 38 to Read Power/Charge control
jim	072.d4	Moved int2irq.vec to wrksp+&22
jim	072.d4	Moved int3irq.vec to wrksp+&24
jim	072.d4	Moved int4irq.vec to wrksp+&26
jim	072.d4	Moved c0irq.vec to wrksp+&28
jim	072.d4	Moved c1irq.vec to wrksp+&2A
jim	072.d4	Moved t1irq.vec to wrksp+&2C
jim	072.d4	Moved t2irq.vec to wrksp+&2E
jim	072.d4	Moved txirq.vec to wrksp+&30
jim	072.d4	Moved tyirq.vec to wrksp+&32
jim	072.d4	Moved s1rirq.vec to wrksp+&34
jim	072.d4	Moved s1rirq.vec to wrksp+&36
jim	072.d4	Moved s2irq.vec to wrksp+&38
jim	072.d4	Moved adcirq.vec to wrksp+&3A
jim	072.d4	Added OS.LCDVDU (&FFB7) and lcdvdu.vec (wrksp+&20)
jim	072.d5	Re-assigned CallOS 37 to Write/Read Power/Charge control
jim	072.d5	Re-assgined CallOS 38 Read Battery Voltage
jim	072.d5	OS.CALLOS now re-entrant
jim	072.d5	Fixed OS.PRINTER
jim	072.d5	Started to add internal logging software
jim	072.d5	Moved OS.LCDVDU to &FFB6
jim	072.d7	Added OS.PRINTERPOLL (&FFB3) and printerpoll.vec (wrksp+&3C)
bob	073	Matched jim & bob sensor lookup tables
bob	073	Added PatchMF
jim	072.dj	Added OS.CALLOS 51 Read keypad press
jim	072.dj	Added hard reset keypad press
jim	072.dk	Added JobCall ReadOutputs
jim	072.do	Changed soft reset of zero page locations
jim	072.do	Changed MotorForward/Backward bitmaps
jim	072.dp	Fixed OS.CALLOS WriteRTCbcd
jim	072.dq	Fixed OS.CALLOS ReadRTCstring for correct 24hr operation
jim	072.dr	Changed reset prompts
bob	074	Added support for Little Bob
jim	072.dy	Added further RTC/CMOS support
jim	072.dB	Removed double hard reset
jim	072.dE	Set _cpu.mode depending on external memory requirement
jim	072.dF	Added Insight code
jim	073	Sub-release
jim	074	Modification to LCD code - uses bsy flag all the time now
jim	074	Fixed OS.CALLOS 42 Write LCD Char Def
jim	074	Fixed OS.CALLOS 43 Read LCD Char Def
jim	075	Added simple battery charge code
jim	075	Fixed JobCall ReadSensorTable
jim	075	Fixed OS.CALLOS 42 Write LCD Char Def
jim	075	Fixed OS.CALLOS 43 Read LCD Char Def
jim	075	Added sleep code
jim	075	Added OS.CALLOS 52 Write Sleep Time
jim	075	Added OS.CALLOS 53 Read Sleep Time
jim	075	Modified battery charge code
jim	076	Modified JobCall ReadSensorTable
jim	076	Modified OS.CALLOS 26 ReadKeypad to do debounce
jim	077	Rewrote battery charging code
jim	077.2	Reduced stop charge threshold to 2
jim	077.3	Increased stop charge threshold to 3
jim	077.3	Added battery voltage averaging
bill	077	Stripped
bill	077	Moved ins to out port
bill	077	Added RTS
bill	077	Changed sensor ID system back to original, using p2.1
bill	077	Dedicated USB/RS selection line, RTS provisioned on p2.3
bill	077	Overload "bounce" timing
bill	078	CTS added
bill	079	Temperature fudge</nowiki>

== Documentation ==

 <nowiki>		Documentation for SmartBox OS 2.066

	The term JobCall is the concept of the routine itself, as opposed to
JobName (which is the actual name associated with it (eg.  NameCode)) and
JobCode (which is the actual number associated with it (eg.  3)).

	The term controller means the SmartBox, or any other incarnation
which may appear in future time !

	The term OS means the controllers' Operating System.


Preview

	There are a number of reasons why using Machine Code on the
controller is more desirable than using the various JobCalls via the serial
link.  One reason is speed, if the task which needs to be performed, has to
be performed very quickly (more quickly than can be achieved via the serial
link at least), then some code must be written to work in the controller
itself to achieve this sort of speed.  If the task required is to be a
"background" task (ie.  a task which may happen while other "things" carry
on as normal, like a change of state of a particular port) then it is far
easier to let the controller do all the work, maybe under interupts, than
continuously poll the controller checking the state of various things. 
Another reason may be that you would like to add another JobCall to the OS,
extending the calls available to external applications (and the user at the
same time), without the user having to write the code himself to achieve the
aim.  For advanced users, there is also the ablity to alter the way the OS
does various things and to have the controller in their "power", for
dedicated tasks etc.

	One advantage of writing IN the controller is that that "function"
is available to any computer using the serial link, and is thus not fixed to
one computer type or even a computer at all, where the controller is used
free running, doing a particular task which doesn't need the intervention of
the user's own computer.


Call types

	There are three different types of machine code routines which can
be added to the controller.  Each one is suited to a more advanced level
than the other, which also relates to the amount of work needed to actually
get the routine working !  The three levels are such:

	a) Simple stand alone routine.  Here the routine is just the routine
itself with no supporting code (ie.  code to integrate with the rest of the
OS).  It has to be called directly, by use of the ExecuteCode JobCall, thus
it usually resides at a fixed address and obviously does not offer the user
friendly way of accessing itself like there is with normal OS calls.

	b) Extended JobCall.  There is one JobCall in the OS (ExtendJob)
which can call various routines residing in memory, each one is identified
by a 8 bit number.  The disadvantages of this way is that the call hasn't
got it's own JobName/JobCode and needs the extra byte to identify itself. 
This is ideal for the quick routine which the user would like to add for
himself without having to resort to the extra code needed for the full
JobCode implementation.

	c) Full JobCall.  This is where the routine can define itself one
(or a number) of JobNames/JobCodes, it can integrate itself into an
extension of the OS in a complete way.  The disadvantage is that extra
coding is needed to deal with the various OS calls it has to service and
that extra work is needed to produce a suitable file to place in the
controller.

	Normally with most processors, including the 65c02, the machine code
produced is produced for a fixed memory address, and it cannot be made to
run in a different place in memory unless extra work is carried out by the
user, or at least a combination of the user and the OS.  For the controller
this is a very severe disadvantage as most extensions are downloaded as
"modules" and to optimise memory a system has to be devised to enable
routines to be placed anywhere in memory, thus allowing no memory to be
wasted.  In the OS there is a routine to do just this, though it does need
some help.  A special version of the users code has to be developed, or
rather it has to be "processed" to add extra information on the end.  Extra
code is needed to set up a few pointers and call the OS routine to relocate. 
See later.


Memory

	The first 256 bytes of memory are somewhat special, most zero page
locations are reserved for use by the OS:

	0	General workspace, used to pass parameters to some OS
			routines, can also be used by other routines DURING
	14		their execution.
	15	Reserved
	6f
	70	Available to the user
	9f
	a0	Accumulator store for irqs (irq_A)
	a1	Two byte counter, decremented at 100hz, useful for temporary
	a2		timing purposes (fcount)
	a3	RAM size, high byte of RAM size of machine, ie. for 32k
			this will be &80 (RAM_size)
	a4	Reserved
	af
	b0	Used by the OS
	ff

	The rest of memory space is used for the processors stack, OS'
buffers, tables, vectors and, of course, the user available memory.

	A breakdown of the rest of memory:

	&100 to &1FF is the 65c02's stack.

	&200-&2FF is used by the OS for various system functions and also
contains the vector table, more on that later.

	&300-&3FF is the serial input buffer.

	&400-&47F is the internal job code call output buffer. (jobout_buf)

	&480-&4FF is the internal job code call input buffer. (jobin_buf)

	&500-&5FF is the job status table.

	&600 to the end of RAM memory is for the user. The user should not
		assume what the top of AVAILABLE memory is and use the
		system variable HIMEM.

	In the controller the maximum limit of RAM is &8000 (which is 32k),
from &8000-&DFFF lies the memory mapped hardware, from &E000 to &FFF9 lies
the OS and from &FFFA to &FFFF lies the 65c02 vectors.

	So the user has his own limits of free memory.  The lowest limit is
called LOMEM and the highest limit is called HIMEM, everything between these
boundaries is termed "available" for use by anyone, the user or the OS. 
Anyone can also claim memory, thus making private to them and not allowing
anyone else to use it.  You do this by altering the value of LOMEM, HIMEM
should not be moved.  Of course anyone claiming memory should first check
that there is enough memory available for the amount they want to claim for. 
To take a common example, a downloadable routine which installs itself as a
extension routine, The download routine will first of all read LOMEM, read
HIMEM, check there is enough memory for the routine, download it to LOMEM
and call it, the downloaded routine will then relocate itself and alter
LOMEM so it is protected.

	There is one other memory limit, this is called TOPMEM, this is the
absolute top limit of RAM, HIMEM will normally equal TOPMEM, but a future OS
may alter HIMEM to below TOPMEM.  TOPMEM should be ignored ideally, and
HIMEM used.


OS Calls

	 The OS has calls (ie.  a jump instruction which you call, which
then calls, via a RAM vector, a routine in the OS) setup near the top of
memory, through these calls you do everything associated with the
controller.  The calls are are such:

 OS_PRINTER	at address &FFB9
 OS_CALLOS	at address &FFBC
 OS_SENDBYTE	at address &FFBF
 OS_READBYTE	at address &FFC2
 OS_SENDJOB	at address &FFC5
 OS_READJOB	at address &FFC8
 OS_DECODEJOB	at address &FFCB

	The address is the one to call for the particular routine.

	OS_PRINTER is reserved for future use.
	OS_CALLOS calls upon the OS to do various things internally.
	OS_SENDBYTE sends a byte out of the serial port.
	OS_READBYTE reads a byte from the serial port.
	OS_SENDJOB 'sends' a value to the JobCall caller.
	OS_READJOB 'reads' a value from the JobCalls caller.
	OS_DECODEJOB decodes the Job number held in A and acts on it.

	Note none of these things should be used in interupt routines,
except OS_CALLOS, of any sort, except if YOU know what state the machine is
in and WHY.


Serial Port

	The serial port on the controller is currently based on the 6850
UART, this need not bother you as the OS deals with the thing entirely by
itself.  The chip is setup by the OS to always have a word format of 8n1 and
a baud rate of 9600, this translates to 960cps.  The 6850 has two divide
rates for the baud rate, the OS only uses one, using the other one is beyond
the scope of this document and shouldn't be neccessary to use.

	Only receive interupts are used, transmission of characters is done
on a polled basis.

	As said, there are two calls OS_READBYTE and OS_SENDBYTE. 
OS_READBYTE tests the serial input buffer and returns the character (if any
in the A register), the c flag states whether there was a character
returned.

 Call	: OS_READBYTE
 Entry	:	A, X, Y, c, z = undefined
 Exit	:	X, Y preserved
		z = undefined
		if c = 1 (no character received)
			A is preserved
		if c = 0 (character received)
			A = character received

	OS_SENDBYTE sends the character in the A register out of the serial
port, taking into consideration flow control etc.

 Call	: OS_SENDBYTE
 Entry	:	A = character to send
		X, Y, c, z = undefined
 Exit	:	A, X, Y, c is preserved
		z = undefined


OS_READJOB and OS_SENDJOB

	To send/receive data from the user (either internally or via the
serial port) you call OS_SENDJOB/OS_READJOB for the next byte.  If your
JobCall requires dynamic use of data, ie.  interaction, then a check of the
enviroment should be done to check the call came from the serial port.  One
example of this is the OS JobCall MultipleServer, which requires dynamic use
of sending a stream of data until a reaction from the user to tell it to
stop.

 Call	: OS_READJOB
 Purpose: To read job value from the user
 Entry	:	A, X, Y, c, z = undefined
 Exit	:	A = byte read
		X, Y is preserved
		c, z = undefined
 Note   : When coming from the serial port it waits for a character to be
 received, if you are doing a serial only call and wish to have a loop
 checking for a character from the user while doing "your own thing", then
 OS_READBYTE should be used.  For internal calls this reads data out of
 jobin_buf.

 Call	: OS_SENDJOB
 Purpose: To give a job value back to the user
 Entry	:	A = byte to give
		X, Y, c, z = undefined
 Exit	:	A, X, Y is preserved
		c, z = undefined
  Note   : This will send either out to the serial port or place a byte in
 jobout_buf.  For internal calls this stores the value in jobout_buf, which
 is allocated 128 bytes, no bound checking is done so sending more than 128
 bytes to OS_SENDJOB will cause corruption of some memory.


OS_DECODEJOB

	 JobCalls in practise are really only used by the user, JobCalls
tend not to call other calls at all, infact you shouldn't really call
another call unless you were called from the serial port.  If you do need to
call another JobCall then you do it like this; with each call you have
associated with it a number, and the call might require some data or give
some data back or both.  With the serial port this is simple, you just send
data down and receive data as it is produced.  You can't do this with
internal calls, and some calls will not let you call them from inside the
controller, you HAVE to call them from outside.  But for the ones which do
let you, you do it with two data blocks, one for input TO the call and one
for output FROM the call.  These are setup in a position in memory
(jobin_buf and jobout_buf), each one has a maximum of 128 bytes and this
should not be overflowed (OS_READJOB and OS_SENDJOB do NOT do any bound
checking).  So to start with you place in the input block the data you want
to give the call (if any), call it, and then act on the data in the output
block (if any).  The OS call OS_DECODEJOB is the one which actually calls
the JobCall handler and eventually the actual routine, you tell the JobCall
handler which call you want by placing the JobCode in the A register.

So for OS_DECODEJOB:

 Call	: OS_DECODEJOB
 Entry	:	A = JobCode
		X, Y, c, z = undefined
		jobin_buf should contain any input data
 Exit	:	A = flag
		X = number of bytes given back by routine
		Y = undefined
		c = status, if set JobCall does not exist
		z = status, if set JobCall cannot be called internally
		jobout_buf contains any data sent from routine

	A typical example would be:

	LDA #readhimem		; JobCode for ReadHimem
	JSR OS_DECODEJOB	; Call the JobCall handler
	LDX jobout_buf		; Read HIMEM from buffer LSB
	LDY jobout_buf+1	; Read HIMEM from buffer MSB
	STX jobin_buf		; Place LSB in input buffer
	STY jobin_buf+1		; Place MSB in input buffer
	LDA #writelomem		; JobCode for WriteLomem
	JSR OS_DECODEJOB	; Call the JobCall handler

which would read HIMEM, and then write LOMEM to be the same value, leaving
no spare memory left.

	The reason why you should not call an internal call from another
internal call is that the same buffers (jobin_buf and jobout_buf) would be
used for both calls, causing conflict between the two calls, or rather to
the originator of the primary call !  The only time it would be safe if is
if you have already got all the data you want from jobin_buf and haven't
placed any in the jobout_buf (it would be lost if you had done).


CallOS

	This OS call does various calls which are completely linked to the
OS, everything from relocating code to reading and writing the hardware
ports.

	As normal, a "function" request value is placed in the A register,
any extra data is put in the X and Y registers and a call to OS_CALLOS is
made, and data is passed back in X, Y, c and z.  The A register will return
0 for all routines except for calls 0 (deemed always to exist anyway), 12 (A
is reserved for future use), 14 (returns 1 instead) and 15 (12, 14 and 15 do
not return 12, 14, 15 in A though), if the routine passes back the same
value in A (the exception being call 0) as you gave it then that OS_CALLOS
function is not supported.

 CALLOS	: 0
 Purpose: Returns the OS version number
 Entry	:	A = 0
		X, Y, c, z = undefined
 Exit	:	A = Hardware release version
		XY = OS version number
		c, z is preserved
 Note	: Hardware version 0 is obsolete
	  Hardware version 1 is SmartBox
	  	VIA at &8030
	  	UART at &8010
	  	ADC at &8000
	  	AUX_PORT (inputs) at &8020 

 CALLOS	: 1
 Purpose: To claim a block of JobCodes
 Entry	:	A = 1
		X = number of JobCodes required
		Y, c, z = undefined
 Exit	:	A = 0
		X = base JobCode, if 0, no big enough block available
		Y = Job ID number, 0 if no big enough block
		c = set if no big enough block
		z is preserved
 Note	: This call claims JobCodes codes from the JobCode list.  JobCodes
are in the range 0 to 255, 0 is special and is the JobCall "Blank".  All the
OS ones are spaced out but an "application" can claim a block of JobCodes,
usually just the 1 call.  If there is not a contigous block big enough then
no JobCodes are allocated and the appropiate result is returned.  The Job ID
is from 0 to 255, 0 is unallocated, 1 is the OS calls, the rest are external
applications, each successful call increments the Job ID returned, meaning a
maximum of 255 successful calls (not important as their is not that many
free calls available !), the Job ID can be used to check whether a JobCall
request is yours.

 CALLOS	: 2
 Purpose: To handle NameCode request for the application.
 Entry	:	A = 2
		XY = block pointing to block of JobNames
		c, z = undefined
		jobin_buf contains JobName (terminated by CR)
		zero_gp3 = JobId (as returned by CALLOS 1)
 Exit	:	A = 0
		XY = undefined
		z is preserved
		if c = 1 (Name not found)
		if c = 0 (Name found)
			jobin_buf contains the JobCode
 Note	: Used via the internal_vec to convert from JobName to job code, the
table format is just a list of the JobNames (each one CR terminated)
terminated by a &ff

 CALLOS	: 3
 Purpose: To handle CodeName request for the application.
 Entry	:	A = 3
		XY = block pointing to block of JobNames
		c, z = undefined
		jobin_buf contains JobCode
		zero_gp3 = job id (as returned by CALLOS 1)
 Exit	:	A = 0
		XY = undefined
		z is preserved
		if c = 1 (JobCode not found)
		if c = 0 (JobCode found)
			jobin contains JobName (terminated by CR)
 Note	: See above

 CALLOS	: 4
 Purpose: To relocate code
 Entry	:	A = 4
		XY = execution address (offset from start of code)
		c, z = undefined
		zero_gp1 = offset address of execution after relocation
		zero_gp2 = offset address of relocation BitMap
		zero_gp3 = length of code to relocate
 Exit	:	No exit, calls begining of code straight away
 Note	: See later section on Relocation

 CALLOS	: 5
 Purpose: To "describe" the enviroment
 Entry	:	A = 5
		X, Y, c, z = undefined
 Exit	:	A = 0
		c, z is preserved
		XY = address of table, format as such:
		1st byte: number of bytes (ie. 14 currently)
		byte 2+:
			address of VIA
			address of ACIA
			address of ADC
			address of AUX_PORT
			address of jobs_status
			address of jobin_buf
			address of jobout_buf
 Note	: It is preferred that this call is consulted first if direct use of
the hardware is going to be used to get the correct addresses, or use CALLOS
0 and decide what addresses/configuration to use from the Hardware version
number.

 CALLOS	: 6
 Purpose: To read a register in the VIA
 Entry	:	A = 6
		X = register (0 to 15)
		Y, c, z = undefined
 Exit	:	A = 0
		Y = value read
		X, c, z is preserved
 Note	: The register number is not checked for range.  This call allows
access to the hardware without actually directly accessing the hardware
yourself.

 CALLOS	: 7
 Purpose: To write to a register in the VIA
 Entry	:	A = 7
		X = register (0 to 15)
		Y = value to write
		c, z = undefined
 Exit	:	A = 0
		X, Y, c, z is preserved
 Note	: See above

 CALLOS	: 8
 Purpose: To read a register in the ACIA
 Entry	:	A = 8
		X = register (0 to 15)
		Y, c, z = undefined
 Exit	:	A = 0
		Y = value read
		X, c, z is preserved
 Note	: See above

 CALLOS	: 9
 Purpose: To write to a register in the ACIA
 Entry	:	A = 9
		X = register (0 to 15)
		Y = value to write
		c, z = undefined
 Exit	:	A = 0
		X, Y, c, z is preserved
 Note	: See above

 CALLOS	: 10
 Purpose: To read a register in the ADC
 Entry	:	A = 10
		X = register (0 to 15)
		Y, c, z = undefined
 Exit	:	A = 0
		Y = value read
		X, c, z is preserved
 Note	: See above

 CALLOS	: 11
 Purpose: To write to a register in the ADC
 Entry	:	A = 11
		X = register (0 to 15)
		Y = value to write
		c, z = undefined
 Exit	:	A = 0
		X, Y, c, z is preserved
 Note	: See above

 CALLOS	: 12
 Purpose: To read a ADC channel
 Entry	:	A = 12
		X = channel number to read (0 to 3)
		Y, c, z = undefined
 Exit	:	A = reserved for future use
		if c = 0 (8 bit reading)
			Y = reading
			X = undefined
		if c = 1 (16 bit reading)
			X = reading (LSB)
			Y = reading (MSB)
		z = undefined
 Note	: The A register MAY not return 0, it is guaranteed though that it
will not return 12.

 CALLOS	: 13
 Purpose: To read a register in the AUX_PORT
 Entry	:	A = 13
		X = register (0 to 15)
		Y, c, z = undefined
 Exit	:	A = 0
		Y = value read
		X, c, z is preserved
 Note	: See above

 CALLOS	: 14 (OS 2.066+)
 Purpose: To start sensor type checking
 Entry	:	A = 14
		X, Y, c, z = undefined
 Exit	:	A = 1
		Y = value read
		X, c, z is preserved
 Note	: A returns 1.  This flags the ADC routines to start checking the
sensors.  After calling this routine, you should poll CALLOS 15 to check
when all the sensors have been checked.

 CALLOS	: 15 (OS 2.066+)
 Purpose: To check the status of sensor checking
 Entry	:	A = 15
		X, Y, c, z = undefined
 Exit	:	A = status
		XY = pointer to sensor types block
		c, z is preserved
 Note	: A does not return 0, though it is guaranteed to not return 15.
	  Status of 0 = checking finished and no futher check pending
	  Status of 1 = Waiting for current ADC channel to finish converting
				before switching sensor checking on
	  Status of >127 = Checking sensor types
	  The block pointed to by XY consists of 4 bytes, each byte
	  	contains the sensor type for the appropiate sensor, a type
	  	of 0 means no sensor present

 CALLOS	: 16 (OS 2.069+)
 Purpose: To set the OS' irq mask for the VIA
 Entry	:	A = 16
		X = EOR mask
		Y = AND mask
		c, z = undefined
 Exit	:	A = 0
 		X = old mask value
		Y = new mask value
		c, z is preserved
 Note	:

 CALLOS	: 17 (OS 2.069+)
 Purpose: To set the OS' irq mask for the ACIA
 Entry	:	A = 17
		X = EOR mask
		Y = AND mask
		c, z = undefined
 Exit	:	A = 0
 		X = old mask value
		Y = new mask value
		c, z is preserved
 Note	:

 CALLOS	: 18 (OS 2.069+)
 Purpose: To set the OS' irq mask for the ADC
 Entry	:	A = 18
		X = EOR mask
		Y = AND mask
		c, z = undefined
 Exit	:	A = 0
 		X = old mask value
		Y = new mask value
		c, z is preserved
 Note	:

 CALLOS	: 19 (OS 2.069+)
 Purpose: To set the ACIA's ctrl register and OS' soft copy
 Entry	:	A = 19
		X = EOR mask
		Y = AND mask
		c, z = undefined
 Exit	:	A = 0
 		X = old mask value
		Y = new mask value
		c, z is preserved
 Note	:

 CALLOS	: 20 (OS 2.069+)
 Purpose: To set the reset vector for battery back RAM support
 Entry	:	A = 20
                XY = address to set reset vector or 0 for read only
		c, z = undefined
 Exit	:	A = 0
 		XY = old reset vector address
		c, z is preserved
 Note	: Sets the reset vector to address supplied and sets check bytes in
workspace.


Vectors

	Some parts of the system are controlled by vectors, vectors also
exist to patch the normal operation of some parts of the system.  Vectors
are RAM pointers, which are called to point to the routine to use.  Being in
RAM this means that they can be altered by the user to allow the user to
modify the operation of part, or all, of a system call.  All the call
routines (eg.  OS_DECODEJOB, OS_READBYTE etc.) are called via a RAM vector. 
There are vectors which the user patches to pick up unknown jobcodes, and to
service requests like NameCode/CodeName etc.

	The vectors are placed at address &200 in memory, each are 2 bytes
long.

 brk_vec	at address &200
 nmi_vec	at address &202
 irq_vec	at address &204
 irq2_vec	at address &206
 sendserial_vec	at address &208
 readserial_vec	at address &20A
 sendjob_vec	at address &20C
 readjob_vec	at address &20E
 decode_job_vec	at address &210
 unknownjob_vec	at address &212
 extjob_vec	at address &214
 centisec_vec	at address &216
 internal_vec	at address &218
 callos_vec	at address &21A
 printer_vec	at address &21C
 reset_vec	at address &21E

	The brk_vec is called whenever there is a BRK error, which should
not occur under normal use, as the controller OS does not make use of BRK
errors.
	The nmi_vec is called whenever there is a NMI request (not really
applicable, as the NMI line is not connected to anything).
	The irq_vec is called whenever there is an interupt.
	The irq2_vec is called whenever an unknown interupt is encountered,
ie.  didnXt come from the controllerXs VIA, ACIA or ADC, or the interupt
from the VIA was not used by the OS.
	The sendserial_vec is called when OS_SENDBYTE is called.
	The readserial_vec is called when OS_READBYTE is called.
	The sendjob_vec is called when OS_SENDJOB is called.
	The readjob_vec is called when OS_READJOB is called.
	The decodejob_vec is called when OS_DECODEJOB is called.  Note that
OS_DECODEJOB first calls a OS routine which sets a flag to say it's been
called internally, JobCode requests the OS gets from the serial port are
called via this vector, with a flag saying "from the serial port".
	The unknownjob_vec is called whenever an unknown JobCode is
encountered.
	The extendedjob_vec is called whenever the ExtendedJob is called,
the A register holds the extension value.
	The centisecond_vec is called 100 times a second from the IRQ
routine from interupts off timer 1 of the VIA.  The OS has its pulsing
routines on the end of this.  Note that you should return with a RTS, not
RTI, you may also corrupt any of the registers.
	The internal_vec is called when some information is needed from
various parts of the system, which includes the OS whch lies on the end of
this vector.  An example is NameCode, which calls this vector to ask
everybody if they recognise the JobName in question.
	The callos_vec is called when OS_CALLOS is called.
	The printer_vec is called when OS_PRINTER is called.
	The reset_vec is called when the OS gets a reset and the internal
check bytes flag the integrity of the RAM.  It is first called with C
cleared for everything to setup vectors and then called with C set for a
foreground "language" application to start up.  Use CALLOS 20 to set this
vector.
	All vectors should be 'daisy chained', ie.  any routine which uses
any of them should store the current value in its own workspace and alter
the vector and at the end of the routine which services the vector should
jump to the original saved value, if this isnXt done the system may 'fall'
down.
	unknown, extendjob and irq2 all point to (in the present OS) to a
routine which just returns.  brk in the current OS just resets the stack and
jumps back to the OS' main idle loop.
	Irqs are reenabled before brk_vec is called


Irq_vec

	This is called when the 65c02 receives an irq from a device.  As the
65c02 signals brk and irq through the same cpu vector the OS first finds out
which one it really was and calls either brk_vec or irq_vec.  It also stores
the A reg at address &a0, as the A reg is corrupted while it finds out which
vector to really call, any irq routine which has claimed the irq should
restore the A reg from &a0 before returning via a RTI, else you should pass
on the call to the old vector owner.

	irq2_vec is called by the OS irq routine if it does not find a irq
it can service (or as been masked out) in as-good-as the same conditions as
irq_vec is called.  The OS has a default irq2_vec handler of restoring A
from &a0 and doing a RTI.


Internal_vec and Unknownjob_vec

	The main operation of extended JobCalls rely on patching some
vectors, two infact.  These two are unknownjob_vec and internal_vec. 
unknownjob_vec is the one which the OS calls to actually tell everybody that
a JobCall has been requested which it does not know about (the JobCall MUST
have been claimed before hand with CALLOS, function 1, or else it is not
passed on).  internal_vec is the one which the OS calls in request to a
NameCode or CodeName.

	The vectors are defined as thus:

 internal_vec

 Function: 0
 Purpose:	Nothing
 Entry	:	A = 0
		X, Y, c, z = undefined
 Exit	:	Leave everything as it is and exit straight away
 Note	: Used for claimed calls

 Function: 1
 Purpose:	NameCode request
 Entry	:	A = 1
		X, Y, c, z = undefined
		jobin_buf contains JobName (CR terminated)
 Exit	:	 if JobName recognised then
			A = 0
			first byte of jobin_buf contains matched JobCode
		if JobName not recognised then
			A = 1
		X, Y, c, z = undefined
 Note	:

 Function: 2
 Purpose:	CodeName request
 Entry	:	A = 2
		X, Y, c, z = undefined
		jobin_buf contains JobCode
 Exit	:	if JobCode recognised then
			A = 0
			jobin_buf contains matched JobName (CR terminated)
		if Code not recognised then
			A = 2
		X, Y, c, z = undefined
 Note	:

	All other calls (ie.  not 0, 1 or 2 should be passed on straight
away for future expansion)

 unknownjob_vec

 Purpose:	To pass on unknown JobCalls to the correct owner
 Entry	:	A = enviroment (0 = internal call, 1 = serial call)
		Y = JobCode
		X = JOB ID of owner
		c, z = undefined
 Exit	:	if jobcode yours then
		if wrong enviroment then
			A = 1
			Y = 0
			X, c, z = undefined
		if right enviroment then
			perform function
			A = 0
			Y = 0
			X, c, z = undefined
		if jobcode not yours then
			pass on with registers unaltered
 Note	:


Starting Up

	The setup procedure for setting up extension job calls is to:

	a) Claim the number of JobCodes you want
		if success:
	b) patch the internal_vec and unknownjob_vec vectors
	c) move LOMEM up to protect your program
	d) do anything else for initial startup you may want to do
	e) return back, ready and waiting

  This in code looks like:

execute
	LDX #no_of_calls	; Number of JobCodes wanted
	LDA #1			; CALLOS, function 1, Claim JobCodes
	JSR OS_CALLOS		; Call CALLOS
	CPX #0			; Check we were given some codes
	BEQ noinstall		; No, don�t bother installing ourself
	STX call		; Store base address of JobCodes allocated
	STY job_id		; Store JOB ID given

	LDA internal_vec	; Get old internal_vec (LSB)
	STA ovec		; Store it
	LDA internal_vec+1	; Get old internal_vec (MSB)
	STA ovec+1		; Store it
	LDA #>internal_handle	; Our internal handler (LSB)
	STA internal_vec 	; Place it in the vector (LSB)
	LDA #<internal_handle	; Our internal handler (MSB)
	STA internal_vec+1	; Place it in the vector (MSB)

	LDA unknownjob_vec	; Get old unknownjob_vec (LSB)
	STA ovec2 		; Store it
	LDA unknownjob_vec+1	; Get old unknownjob_vec (MSB)
	STA ovec2+1		; Store it
	LDA #>job_handle	; Our unknown job handler (LSB)
	STA unknownjob_vec	; Place it in the vector (LSB)
	LDA #<job_handle	; Our unknown job handler (MSB)
	STA unknownjob_vec+1	; Place it in the vector (MSB)

	LDX #>WriteLomem	; Point to JobName
	LDY #<WriteLomem
	JSR findjob		; Find WriteLomem code
	BEQ noinstall		; Doesn't exist !
	LDX #>end_of_code	; End of code (LSB)
	LDY #<end_of_code	; End of code (MSB)
	STX jobin_buf		; Place it in jobin_buf (LSB)
	STY jobin_buf+1		; Place it in jobin_buf+1 (MSB)
	JSR OS_DECODEJOB	; Call JobCall handler

noinstall
	RTS			; End - return to OS

findjob
	STX zero.gp1		; Zero page
	STY zero.gp1+
	LDY #0
findthisjoblo
	LDA (zero.gp1),Y
	STA jobin.buf,Y		; Store name in jobin_buf
	INY
	CMP #13
	BNE findthisjoblo
	LDA #3			; NameCode
	JSR OS.DECODEJOB	; Call NameCode
	LDA jobout.buf		; Get returned value
	RTS

WriteLomem	STR "WriteLomem"

	This will setup the various vectors and memory pointers for the
applicaion, the actual routines (internal_handle and job_handle) are fairly
straight forward and simple:

internal_handle
	CMP #1			: Is it function call 1 (NameCode) ?
	BNE internal_handle_2	; No, check for function 2
	LDA job_id		; Get our JOB ID number
	STA zero_gp3		; Place it in zero_gp3 for CALLOS
	LDX #>job_names		; Our Job name table (LSB)
	LDY #<job_names		; Our Job name table (MSB)
	LDA #2			; CALLOS function 2
	JSR OS_CALLOS		; Call CALLOS
	BCC internal_yes	: Found, go off and claim call
	LDA #1			; Not found, restore A
	JMP (ovec)		; Call back to old vector

internal_handle_2
	CMP #2			; Is it function call 2 (CodeName) ?
	BNE internal_handle_3	; No, unknown, pass on
	LDA job_id		; Get our JOB ID
	STA zero_gp3		; Place it in zero_gp3 for CALLOS
	LDX #>job_names		; Our Job name table (LSB)
	LDY #<job_names		; Our Job name table (MSB)
	LDA #3			; CALLOS function 3
	JSR OS_CALLOS		; Call CALLOS
	BCC internal_yes	; Found, go off and claim call
	LDA #2			; Not found, restore A
	JMP (ovec)		; Call back to old vector

internal_yes
	LDA #0			; We want to claim call for some reason

internal_handle_3
	JMP (ovec)		; Call back to old vector

job_handle
	PHA			; Mark sure to preserve A
	CPY call		; Check call wanted against base of ours
	BCC job_handle_no	; Less than our base, so definately not ours
	TYA
	SBC #no_of_calls	; Subtract number of calls we have
	CMP call		; Now compare with base
	BCC job_handle2		; Yes, one of ours

job_handle.no
	PLA			; Restore A
	JMP (ovec2)		; Call back to old vector

job_handle2
	TYA
	SEC
	SBC call		; Subtract our base from call
	ASL A			; Times by 2 for offset into table
	TAY			; Place in Y
	LDA job_run_table,Y	; Get LSB of routine
	STA zero_gp1		; Store it for indirect jump (LSB)
	LDA job_run_table+1,Y	; Get MSB of routine
	STA zero_gp1+1		; Store it for indirect jump (MSB)
	PLA			; Restore A
	JMP (zero_gp1)		; Call our relevant routine

job_names			; List of our JobNames
	STR "TestJob"		; Test job name
	DFB &FF			; &FF - marks end of table

job_run_table			; List of routine addresses to match Jobs
	DFW job_TestJob		; Test job routine


Relocation

	The relocation method used will not do a complete relocation, ie. 
from ANY address to ANY address.  The only constraint on the addresses is
that they must be the same offset in the page, which means, &2602 and &3402
is alright but &2602 and &3455 is not, ie.  the difference between the two
addresses must be a multiple of 256 bytes, as only the MSB is altered, this
should not cause any real problems.  What is meant by the two addresses is
the address the code was originally assembled at and the address it wants
relocating to.  Because of this programs must be multiples of 256 bytes, ie. 
the low byte of LOMEM must ALWAYS be 0, your program should be padded out.

	The relocation mechanism works by having a table, and to each byte
of code there is one BIT, if unset it means the byte of code should not be
relocated, else it should be, thus the BitMap table is 8 times smaller than
the code.  To generate the BitMap you have to assemble the code at two
different places, and compare both sets of assembled code against each
other, the differences are where the code is to be relocated.  The code
which is sent up to the controller is assumed to be assembled at address
&100, so the first code should be assembled at &100, the other one should be
assembled at another address, say &600, and the first one be sent up with
the BitMap.  A program is availble for the Elk/Beeb/Arc with 65Tube/Mac with
BBC BASIC to compare the two files and create the BitMap.

	All the program has to do to relocate itself is execute this bit of
code first of all: (address is the base address of the program, ie.  &100
for the downloaded version)

execcall
	LDA #>(execute-address)	; Final execution address offset (LSB)
	STA zero_gp1
	LDA #<(execute-address)	; Final execution address offset (MSB)
	STA zero_gp1+1

	LDA #>(BitMap-address)	; BitMap address offset (LSB)
	STA zero_gp2
	LDA #<(BitMap-address)	; BitMap address offset (MSB)
	STA zero_gp2+1

	LDA #>(execcall-address); Length of data to relocate (LSB)
	STA zero_gp3
	LDA #<(execcall-address); Length of data to relocate (MSB)
	STA zero_gp3+1

	TXA			; Execcall REAL address
	SEC
	SBC #>(execcall-address); Subrtract length
	TAX			; Put it back in X
	TYA			; Ditto for MSB
	SBC #<(execcall-address)
	TAY
	LDA #4			; CALLOS function for Relocate
	JMP OS_CALLOS		; Call CALLOS

BitMap				; BitMap start

	This will relocate the code and automatically call the execution
address, which should be the initialisation code (ie.  setup internal_vec
and unknownjob_vec etc.).  "address" is the address the code is started to
assemble at, &100 for the version to be uploaded.  The upload routine should
pass in X and Y (via ExecuteCode) the address of the start of execcall, this
means that the routine can tell where it is in memory, subtracting the
length gives the start of the code to relocate.


Layout Summary

	The layout of a full application should be like this by now:

	start of code
		program job codes, data etc.
		internal handler
		job handler
	end of code
		initialisation (setup internal etc.)
	end of code to be relocated
		execution (relocation)
		relocation BitMap

	Because of memory space the initialisation code should be placed
outside the reserved memory limit of the program, as it is only called once
and not needed again.


 Other miscellaneous calls:

Call		: OS_PRINTER
Purpose	: To place a character in the printer buffer
Entry		: A = character to send
		  X, Y, c, z = undefined
Exit		: A, X, Y is preserved
		  if c = 0 (printed)
			The printer is on and the character was inserted
		  if c = 1 (not printed)
			The printer is off and the character was forgotten
		  z = undefined
Note		: The character goes into the printer buffer and will be
actually sent to the printer when the printer asks for it. If the printer
was not awake to begin with, an attempt is made to wake it up, thus
meaning that in some circumstances when the printer wasn't ready a
character may be lost, this cannot be helped. If the printer is off (via
the BCD switch) then the character will be forgotten as the Printer Buffer
is inactive.


  The module is located at &8000 in memory, and should be a EPROM placed
in the second ROM socket in the controller (ie. the top RAM socket). This
module is primary designed to turn the Controller into a dedicated task,
making it perform some function from switch on. It could also be used to
add more permant JobCalls to the Controller, in the process taking up much
less RAM), but because of there being only one Module present this feature
is limited, and is much more suited to a collection of the user's own
personal routines.
  For the OS to recognise a module as being in place the text "Module" is
looked for, the layout of a module should be like this (starting at
&8000):

Offset		value			comment
 0		"Module"		The OS checks for this string
 6		0			End of check string
 7		Language entry		Address of 'Language' entry
 9		Service entry		Address of 'Service' entry
11		"<Module Title>" 	Module title
		0			End of Module title

		"<Module part>"		Part Module Title
		0			End of Part Module Title
		"x.xx"			Part version number

		&FF			End of parts list

  The language entry is a 2 byte value holding the address of the language
entry routine, this is called on reset, if the BCD is set correctly. A
value of less than &8000 means there is no valid language entry and any
language calls are ignored. If a RTS is made the OS carries on as it would
have if there wasn't a language call.

  The service entry is a 2 byte value holding the address of the service
entry routine, this is called at various appropiate moments with service
numbers in A. A list of current calls is thus:

	  0	- Not used
	  1	- Unknown Job Code
	  2	- Centisecond call
	  3	- Irq2 (unknown IRQ)
	  4	- internal_vec call (exit with A=0 to claim)
	254	- RESET
	255	- BRK

  On exit all registers and flags should be preserved. For call 1 the
unknown job value is held in the Y register, the enviroment is held in the
X register, on exit, X should contain the flag, as A does from the exit of
unknownjob_vec. For the rest of calls, X and Y are undefined.

  For both Service and Language entry points, a value of 0 means "there is
no valid routine" and the module isn't called for that type of entry.



  Finally a full implementation of a JobCall, from start to finish.

 DIM data% &1000
 :
 no_of_calls = 1
 :
 VIA = &E030
 ACIA = &E010
 ADC = &E000
 AUX_PORT = &E020
 brk_vec = &200
 nmi_vec = &202
 irq_vec = &204
 irq2_vec = &206
 sendserial_vec = &208
 readserial_vec = &20A
 sendjob_vec = &20C
 readjob_vec = &20E
 decodejob_vec = &210
 unknownjob_vec = &212
 extjob_vec = &214
 centisec_vec = &216
 internal_vec = &218
 callos_vec = &21A
 printer_vec = &21C
 zero_gp1 = 0
 zero_gp2 = 2
 zero_gp3 = 4
 zero_gp4 = 6
 zero_gp5 = 8
 zero_gp6 = 10
 zero_gp7 = 12
 zero_gp8 = 14
 zero_gp9 = 16
 zero_gp10 = 18
 user_reserved = &70
 irq_A = &A0
 fcount = &A1
 RAM_size = &A3
 jobout_buf = &400
 jobin_buf = &480
 OS_PRINTER = &FFB9
 OS_CALLOS = &FFBC	
 OS_SENDBYTE = &FFBF
 OS_READBYTE = &FFC2
 OS_SENDJOB = &FFC5
 OS_READJOB = &FFC8
 OS_DECODEJOB = &FFCB
 :
 FOR create=1 TO 2
 :
 FOR pass%=4 TO 7 STEP 3
 P%=&100*create : O%=data%
 [OPT pass%
 :
 .job_DemoJob
 CMP #1
 BEQ DemoJob_go
 LDA #1
 LDY #0
 RTS
 /
 .DemoJob_go




 :
 .internal_handle
 CMP #1			; Is it function call 1 (NameCode) ?
 BNE internal_handle_2		; No, check for function 2
 /
 LDA job_id			; Get our JOB ID number
 STA zero_gp3			; Place it in zero_gp3 for CALLOS
 LDX #job_names MOD 256	; Our Job name table (LSB)
 LDY #job_names DIV 256	; Our Job name table (MSB)
 LDA #2			; CALLOS function 2
 JSR OS_CALLOS			; Call CALLOS
 BCC internal_yes		; Found, go off and claim call
 LDA #1			; Not found, restore A
 JMP (ovec)			; Call back to old vector
 /
 .internal_handle_2
 CMP #2			; Is it function call 2 (CodeName) ?
 BNE internal_handle_3		; No, unknown, pass on
 /
 LDA job_id			; Get our JOB ID
 STA zero_gp3			; Place it in zero_gp3 for CALLOS
 LDX #job_names MOD 256	; Our Job name table (LSB)
 LDY #job_names DIV 256	; Our Job name table (MSB)
 LDA #3			; CALLOS function 3
 JSR OS_CALLOS			; Call CALLOS
 BCC internal_yes		; Found, go off and claim call
 LDA #2			; Not found, restore A
 JMP (ovec)			; Call back to old vector
 /
 .internal_yes
 LDA #0			; We want to claim call for some reason
 /
 .internal_handle_3
 JMP (ovec)			; Call back to old vector
 :
 .job_handle
 PHA				; Make sure to preserve A
 CPY call			; Check call wanted against base of ours
 BCC job_handle_no		; Less than our base, so definately not ours
 TYA
 SBC #no_of_calls		; Subtract number of calls we have
 CMP call			; Now compare with base
 BCC job_handle2		; Yes, one of ours
 /
 .job_handle.no
 PLA				; Restore A
 JMP (ovec2)			; Call back to old vector
 /
 .job_handle2
 TYA
 SEC
 SBC call			; Subtract our base from call
 ASL A				; Times by 2 for offset into table
 TAY				; Place in Y
 LDA job_run_table,Y		; Get LSB of routine
 STA zero_gp1			; Store it for indirect jump (LSB)
 LDA job_run_table+1,Y		; Get MSB of routine
 STA zero_gp1+1		; Store it for indirect jump (MSB)
 PLA				; Restore A
 JMP (zero_gp1)		; Call our relevant routine
 :
 .job_names			; List of our JobNames
 EQUS "DemoJob":EQUB 13	; Test job name
 /
 EQUB &FF			; &FF - marks end of table
 :
 .job_run_table		; List of routine addresses to match Jobs
 EQUW job_DemoJob		; Test job routine
 :
 .call   : EQUB 0		; Store for our JobCode base
 .job_id : EQUB 0		; Store for our JobId
 .ovec   : EQUW 0		; Store for old internal_vec value
 .ovec2  : EQUW 0		; Store for old unknownjob_vec value
 :
 EQUS STRING$(&100-(P% MOD 256),CHR$0)
 .end_of_code			; end_of_code should be on page boundry
 :
 .execute
 LDX #no_of_calls		; Number of JobCodes wanted
 LDA #1			; CALLOS, function 1, Claim JobCodes
 JSR OS_CALLOS			; Call CALLOS
 STX call			; Store base address of JobCodes allocated
 STY job_id			; Store JOB ID given
 CPX #0			; Check we were given some codes
 BEQ noinstall			; No, don't bother installing ourself
 /
 LDA internal_vec		; Get old internal_vec (LSB)
 STA ovec			; Store it
 LDA internal_vec+1		; Get old internal_vec (MSB)
 STA ovec+1			; Store it
 LDA #internal_handle MOD 256	; Our internal handler (LSB)
 STA internal_vec		; Place it in the vector (LSB)
 LDA #internal_handle DIV 256	; Our internal handler (MSB)
 STA internal_vec+1		; Place it in the vector (MSB)
 /
 LDA unknownjob_vec		; Get old unknownjob_vec (LSB)
 STA ovec2			; Store it
 LDA unknownjob_vec+1		; Get old unknownjob_vec (MSB)
 STA ovec2+1			; Store it
 LDA #job_handle MOD 256	; Our unknown job handler (LSB)
 STA unknownjob_vec		; Place it in the vector (LSB)
 LDA #job_handle DIV 256	; Our unknown job handler (MSB)
 STA unknownjob_vec+1		; Place it in the vector (MSB)
 /
 LDX #end_of_code MOD 256	; End of code (LSB)
 LDY #end_of_code DIV 256	; End of code (MSB)
 STX jobin_buf			; Place it in jobin_buf (LSB)
 STY jobin_buf+1		; Place it in jobin_buf+1 (MSB)
 LDA #65			; JobCode for WriteLomem
 JSR OS_DECODEJOB		; Call JobCall handler
 /
 .noinstall
 RTS				; End - return to OS
 :
 .execcall
 LDA #>(execute-address)	; Final execution address offset (LSB)
 STA zero_gp1
 LDA #<(execute-address)	; Final execution address offset (MSB)
 STA zero_gp1+1
 /
 LDA #>(BitMap-address)	; BitMap address offset (LSB)
 STA zero_gp2
 LDA #<(BitMap-address)	; BitMap address offset (MSB)
 STA zero_gp2+1
 /
 LDA #>(execcall-address)	; Length of data to relocate (LSB)
 STA zero_gp3
 LDA #<(execcall-address)	; Length of data to relocate (MSB)
 STA zero_gp3+1
 /
 TXA				; Execcall REAL address
 SEC
 SBC #>(execcall-address)	; Subrtract length
 TAX				; Put it back in X
 TYA				; Ditto for MSB
 SBC #<(execcall-address)
 TAY
 LDA #4			; CALLOS function for Relocate
 JMP OS_CALLOS			; Call CALLOS
 /
 .BitMap			; BitMap start
 :
 ]
 NEXT
 :
 OSCLI "SAVE code"+STR$create+" "+STR$~data%+" "+STR$~O%
 :
 NEXT</nowiki>