Editing SmartBox OS (section)

=== 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:

{|class="calltable"
|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:

 <nowiki>	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</nowiki>

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).