The NC100 Jumpblock Entries
Most of the following routines return with the carry flag set if successful and, unless otherwise
stated, you should assume that AF is corrupt on return and that other registers are preserved.
Where you see All registers preserved this includes the flags, but NOT the alternate registers.
In fact the alternate register contents can NEVER be assumed to be preserved as they are used as scratch
registers in time-critical routines.
To use any one of these routines just load the registers as described and then call the relevant address.
Although the running of a routine may involve a different ROM bank being switched in, this mechanism is
invisible to the caller. So, for example, to print a capital A you could use the following (pretty
useless, but explanatory) example:
10 CLS
20 txtoutput=&B833
30 FOR pass=0 TO 3 STEP 3
40 [
50 OPT pass
60 LD A, ASC("A")
70 CALL txtoutput
80 RET
90 ]
100 NEXT
EDITBUF - &B800
Action:
A line editor with options. A zero-terminated string may be passed in buffer (HL).
This will display the initial contents.
| Entry conditions:
|
| HL: | | Pointer to input buffer
|
| B: | | Size of buffer (excluding terminating zero)
|
| A: | | Flags:
bit 2 = 1 - Up and down cursor keys terminate input
bit 3 = 1 - Input not echoed
bit 4 = 1 - Delete trailing spaces
bit 5 = 1 - Edit unless characters entered
bit 6 = 1 - Dotty background (character 176)
Other bits must be set to zero.
|
| Exit conditions
|
| c=0 & z=1 | | [Stop] pressed
|
| c=1 & z=1 | | Empty string input
|
| c=1 & z=0 | | At least one character entered
|
| HL | | Preserved
|
| BC | | Last key token (or -1 if [Stop] used to terminate)
|
KMCARRETURN - &B803
Action:
Returns a token to the keyboard buffer. This is useful for determining which token is due next without
removing it from the buffer, by first reading it an then returning it.
| Entry conditions
|
| BC | | The token
|
| Exit conditions
|
| All registers preserved
|
KMREADKBD - &B806
Action:
Gets a key token if there is one. It does not wait but checks put-back characters and expands macros. it
also returns tick event tokens, if enabled.
| Exit conditions:
|
| C=1: | | BC=token (B=0 for simple character)
|
| C=0: | | No key token available
|
KMSETEXPAND - &B809
Action:
Defines a macro string
| Entry conditions:
|
| BC: | | Macro token (between 256 and 383)
|
| HL: | | Points to new macro string (the first byte is the length, followed by the string,
which need to be zero terminated)
|
| Exit conditions:
|
| c=1 | | Macro defined successfully
|
| c=0 | | Insufficient room in the buffer (The buffer size is user configurable)
|
KMSETTICKCOUNT - &B80C
Action:
Enables the ticker event. There are 100 ticks per second. When a ticker event occurs a special value of
941 is returned by KMREADKBD (&B806).
| Entry conditions:
|
| HL: | | Number of ticks before first event
|
| DE: | | Number of ticks between events
|
| Exit conditions:
|
| All registers preserved
|
KMWAITKBD - &B80F
Action:
Waits for a key token. It uses KMREADKBD (&B806) and checks put-back characters and expands macros.
It also returns tick event tokens if enabled.
| Exit conditions:
|
| C=1: | | BC=Token (B=0 for a simple character)
|
READBUF - &B812
Action:
A line editor. See also EDITBUF (&B800).
| Entry conditions:
|
| HL: | | Pointer to input buffer (empty
|
| B: | | Size of buffer (excluding terminating zero)
|
| Exit conditions:
|
| c=0 & z=1: | | [Stop] pressed
|
| c=1 & z=1: | | Empty string input
|
| c=1 & z=0: | | At least one character entered
|
| BC: | | Last key token (or -1 if [Stop] used to terminate)
|
| HL: | | Preserved
|
TESTESCAPE - &B815
Action:
Tests whether an Escape key has been pressed (either [Stop] or [Function]). It waits for a key if one is
found in the keyboard buffer.
| Exit conditions:
|
| c=1: | | No Escape key in buffer, or Escape key in buffer but [Stop] not pressed
|
| c=0: | | Escape key in buffer and [Stop] then pressed
|
| A: | | Preserved
|
COL1 - &B818
Action:
If the cursor is at the start of a line it does nothing, otherwise it moves the cursor to the start of
next line (within the current window).
| Exit conditions:
|
| All registers preserved
|
COL1TEXT - &B81B
Action:
The same as TEXTOUT (&B81E), but it calls COL1 (&B818)first.
| Exit conditions:
|
| All registers preserved
|
TEXTOUT - &B81E
Action:
Displays a string.
| Entry conditions:
|
| HL: | | Pointer to a zero-terminated string.
WARNING - HL must not point into an upper ROM!
|
| Exit conditions:
|
| All registers preserved
|
TEXTOUTCOUNT - &B821
Action:
The same as TEXTOUT (&B81E), but returns a character count in B.
| Exit conditions:
|
| B: | | Character count
|
TXTCLEARWINDOW - &B824
Action:
Clears the current window and moves the cursor to the top-left of it.
| Exit conditions:
|
| All registers preserved
|
TXTCUROFF - &B827
Action:
Removes the cursor from the screen.
| Exit conditions:
|
| All registers preserved
|
TXTCURON - &B82A
Action:
Displays the cursor on the screen.
| Exit conditions:
|
| All registers preserved
|
TXTGETCURSOR - &B82D
Action:
Returns the cursor position.
| Exit conditions:
|
| H: | | Column (between 0 and 79)
|
| L: | | Row (between 0 and 7)
|
TXTGETWINDOW - &B830
Action:
Returns the window coordinates.
| Exit conditions:
|
| H: | | Left column (between 0 and 79)
|
| L: | | Top row (between 0 and 7)
|
| D: | | Right column (between 0 and 79)
|
| E: | | Bottom row (between 0 and 7)
|
| c=0: | | Window is whole screen
|
| c=1: | | A smaller window has been created
|
TXTOUTPUT - &B833
Action:
Displays a character or acts on control code.
| Entry conditions:
|
| A: | | character:
A = 7: Beep
A = 10: Line Feed
A = 13: Carriage Return
All other values are displayed as a character (the same as the PC character set)
|
| Exit conditions:
|
| All registers preserved
|
TXTSETCURSOR - &B836
Action:
Moves the cursor to a new position.
| Entry conditions:
|
| H: | | Column (between 0 and 79)
|
| L: | | Row (between 0 and 7)
|
| Exit conditions:
|
| All registers preserved
|
TXTSETWINDOW - &B839
Action:
Defines a new window.
| Entry conditions:
|
| H: | | Left column (between 0 and 79)
|
| L: | | Top row (between 0 and 7)
|
| D: | | Right column (between 0 and 79)
|
| E: | | Bottom row (between 0 and 7)
|
| Exit conditions:
|
| All registers preserved
|
TXTWRCHAR - &B83C
Action:
Displays a character. Control codes are also displayed as characters rather than being acted upon.
| Entry conditions:
|
| A: | | Character. All values are displayed as per the PC character set.
|
| Exit conditions:
|
| All registers preserved
|
TXTBOLDOFF - &B83F
Action:
Resets the bold attribute. The next time text is written to the screen it will be without this attribute.
| Exit conditions:
|
| All registers preserved
|
TXTBOLDON - &B842
Action:
Sets the bold attribute. The next time text is written to the screen it will be with this attribute.
| Exit conditions:
|
| All registers preserved
|
TXTINVERSEOFF - &B845
Action:
Resets the inverse attribute. The next time text is written to the screen it will be without this attribute.
| Exit conditions:
|
| All registers preserved
|
TXTINVERSEON - &B848
Action:
Sets the inverse attribute. The next time text is written to the screen it will be with this attribute.
| Exit conditions:
|
| All registers preserved
|
TXTUNDERLINEOFF - &B84B
Action:
Resets the underline attribute. The next time text is written to the screen it will be without this attribute.
| Exit conditions:
|
| All registers preserved
|
TXTUNDERLINEON - &B84E
Action:
Sets the underline attribute. The next time text is written to the screen it will be with this attribute.
| Exit conditions:
|
| All registers preserved
|
MCPRINTCHAR - &B851
Action:
Sends a character to the printer.
| Entry conditions:
|
| A: | | Character
|
| Exit conditions:
|
| c=0: | | Successful
|
| c=1: | | Not sent
|
| A: | | Preserved
|
MCREADYPRINTER - &B854
Action:
Tests whether the printer is ready.
| Exit conditions:
|
| c=0: | | Busy
|
| c=1: | | Ready
|
| A: | | Preserved
|
MCSETPRINTER - &B857
Action:
Sets the printer type to be used by MCPRINTCHAR (&B851) and
MCREADYPRINTER (&B854).
| Entry conditions:
|
| A: | | Printer type:
0 = Parallel
1 = Serial
|
| Exit conditions:
|
| All registers preserved
|
PADINITSERIAL - &B85A
Action:
Initialises the serial port using the global configured settings and turns on the UART and 4711.
To prolong battery life, do not call this until needed.
| Exit conditions:
|
| All registers preserved
|
PADINSERIAL - &B85D
Action:
Reads a character from the serial port.
| Exit conditions:
|
| c=1: | | Successful, A=character
|
| c=0: | | No character read
|
PADOUTPARALLEL - &B860
Action:
Sends a character to the parallel port.
| Entry conditions:
|
| A: | | Character
|
| Exit conditions:
|
| c=1: | | Succesful
|
| c=0: | | Not sent
|
| A: | | Preserved
|
PADOUTSERIAL - &B863
Action:
Sends a character to the serial port.
| Entry conditions:
|
| A: | | Character
|
| Exit conditions:
|
| c=1: | | Successful
|
| c=0: | | Not sent
|
| A: | | Preserved
|
PADREADYPARALLEL - &B866
Action:
Tests whether the parallel port is ready.
| Exit conditions:
|
| c=0: | | Busy
|
| c=1: | | Ready
|
| A: | | Preserved
|
PADREADYSERIAL - &B869
Action:
Tests whether the serial port is ready.
| Exit conditions:
|
| c=0: | | Busy
|
| c=1: | | Ready
|
| A: | | Preserved
|
PADRESETSERIAL - &B86C
Action:
Turns off the UART and 4711. To prolong battery life call this as soon as you have finished using the serial port.
| Exit conditions:
|
| All registers preserved
|
PADSERIALWAITING - &B86F
Action:
Tests whether there is a character waiting to be read from the serial port.
| Exit conditions:
|
| c=1: | | Character waiting
|
| c=0: | | No character waiting
|
PADGETTICKER - &B872
Action:
Returns the address of a four-byte 100Hz ticker.
| Exit conditions:
|
| HL: | | The address of the least significant byte (first of four)
|
PADGETTIME - &B875
Action:
Reads the time and date from the Real Time Clock.
| Entry conditions:
|
| HL: | | Points to a seven-byte buffer to use.
|
| Exit conditions:
|
| HL: | | Preserved. The buffer contains the seven bytes of data:
byte 0 = year (low)
byte 1 = year (high)
byte 2 = month
byte 3 = date
byte 4 = hour
byte 5 = minute
byte 6 = second
|
PADSETALARM - &B878
Action:
Sets the ALARM date and time (within the next month).
| Entry conditions:
|
| HL: | | Points to a three-byte data area:
byte 0 = date
byte 1 = hour
byte 2 = minute
|
| Exit conditions:
|
| All registers preserved
|
PADSETTIME - &B87B
Action:
Sets the Real Time Clock date and time.
| Entry conditions:
|
| HL: | | Points to a seven-byte data area:
byte 0 = year (low)
byte 1 = year (high)
byte 2 = month
byte 3 = date
byte 4 = hour
byte 5 = minute
byte 6 = second
|
| Exit conditions:
|
| All registers preserved
|
HEAPADDRESS - &B87E
Action:
Obtains the address of a memory block for a given memory handle.
| Entry conditions:
|
| DE: | | Memory handle
|
| Exit conditions:
|
| HL: | | Pointer to memory block
|
HEAPALLOC - &B881
Action:
Allocates a block of memory from the heap.
| Entry conditions:
|
| DE: | | Number of bytes to allocate
|
| Exit conditions:
|
| HL=0: | | 0 if failed
|
| HL<>0: | | Memory handle in the range 1 - 63
|
NOTE: HEAPADDRESS (&B87E) must be used to get a pointer to the memory block
unless the block is locked with HEAPLOCK (&B887). HEAPADDRESS (&B87E)
must be called each time the memory block is used as it may have moved!
HEAPFREE - &B884
Action:
Frees a block of memory.
| Exit conditions:
|
| HL: | | Preserved
|
| BC: | | Preserved
|
NOTE: The memory handle passed must be a valid handle returned by HEAPALLOC (&B881)
or HEAPREALLOC (&B88D). This is not validated.
HEAPLOCK - &B887
Action:
Locks or unlocks a memory block.
| Entry conditions:
|
| DE: | | Memory handle
|
| BC=0: | | The block is locked. It will not be moved until unlocks so fixed addresses can be used as pointers into the block
|
| BC<>0: | | The block is unlocked
|
HEAPMAXFREE - &B88A
Action:
Returns the largest block size that can be allocated.
| Exit conditions:
|
| HL: | | Largest free block size in bytes
|
HEAPREALLOC - &B88D
Action:
Changes the size of an allocated memory block.
| Entry conditions:
|
| DE: | | Memory handle
|
| BC: | | New size for memory block
|
| Exit conditions:
|
| HL=0: | | Failed. The old block will not be freed but could have moved.
|
| HL<>0: | | Successful
|
NOTE: If the block is being expanded, it must be assumed that the base of the memory block will
be moved (even if the block cannot actually be expanded), so HEAPADDRESS (&B87E) must
be called afterwards. If the block is being contracted, the base will not move.
FCLOSE - &B890
Action:
Closes a file.
| Entry conditions:
|
| DE: | | File handle
|
| Exit conditions:
|
| c=1: | | Successful
|
| c=0: | | Failed
|
FERASE - &B893
Action:
Erases a file.
| Entry conditions:
|
| HL: | | Zero-terminated filename
|
| Exit conditions:
|
| c=1: | | Succesful
|
| c=0: | | Error (file not found)
|
FINBLOCK - &B896
Action:
Reads a block from a file.
| Entry conditions:
|
| DE: | | File handle
|
| HL: | | Buffer
|
| BC: | | Number of bytes to read (greater than 0)
|
| Exit conditions:
|
| c=1: | | End of file not reached
|
| c=0: | | Eof (or error?)
|
| BC: | | Number of bytes read
|
| HL: | | Address of last byte read
|
FINCHAR - &B899
Action:
Reads a byte from file.
| Entry conditions:
|
| DE: | | File handle
|
| Exit conditions:
|
| c=1: | | Successful, A=character
|
| c=0: | | A corrupt if end of file reached, other registers preserved
|
FINDFIRST - &B89C
Action:
Finds the first file. SETDTA (&B8C6) must have been called first.
| Exit conditions:
|
| HL=0: | | No files
|
| HL<>0: | | HL points to a file info structure. The first item in the structure is the
filename, zero-terminated (up to 12 characters long), offset 13 is the attribute byte - see
FGETATTR (&B8CF) for futher details on attributes, Offset 14 and 15 are the file size in bytes (low, high)
|
FINDNEXT - &B89F
Action:
Finds the next file. FINDFIRST (&B89C) must have been called first.
FOPENIN - &B8A2
Action:
Opens a file for input.
| Entry conditions:
|
| HL: | | Points to zero-terminated filename
|
| Exit conditions:
|
| c=1: | | Succesful, DE=file handle
|
| c=0: | | Failed (file not found, DE=Corrupt
|
| A: | Corrupt, other registers preserved
|
FOPENOUT - &B8A5
Action:
Opens a file for output.
| Entry conditions:
|
| HL: | | Points to zero-terminated filename
|
| Exit conditions:
|
| c=1: | | Succesful, DE=file handle
|
| c=0: | | Failed (out of memory/too many files/files exists), DE=Corrupt
|
| A: | | Corrupt, other registers preserved
|
FOPENUP - &B8A8
Action:
Opens a file for input and output. The file must already exist.
| Entry conditions:
|
| HL: | | Points to zero-terminated filename
|
| Exit conditions:
|
| c=1 | | Successful, DE=file handle
|
| c=0 | | File not found, DE=Corrupt
|
| A: | | Corrupt, other registers preserved
|
FOUTBLOCK - &B8AB
Action:
Writes a block to file.
| Entry conditions:
|
| DE: | | File handle
|
| HL: | | Buffer
|
| BC: | | Number of bytes to write (greater than 0)
|
| Exit conditions:
|
| c=1: | | Succesful
|
| c=0: | | Error
|
| BC: | | Number of bytes written
|
| HL: | | Address after last byte written
|
FOUTCHAR - &B8AE
Action:
Writes a byte to a file.
| Entry conditions:
|
| DE: | | File handle
|
| A: | | Character
|
| Exit conditions:
|
| c=1: | | Succesful
|
| c=0: | | A=Corrupt if end of file reached, other registers preserved
|
FRENAME - &B8B1
Action:
Renames a file.
| Entry conditions:
|
| HL: | | Points to zero-terminated old filename
|
| DE: | | Points to zero-terminated new filename
|
| Exit conditions:
|
| c=1: | | Succesful
|
| c=0: | | Error (file not found)
|
FSEEK - &B8B4
Action:
Moves the file pointer to a position within a file.
| Entry conditions:
|
| DE: | | File handle
|
| BC: | | Offset from start of file
|
| Exit conditions:
|
| c=1: | | Successful
|
| c=0: | | Offset past enf of file (pointer not changed)
|
FSIZE - &B8B7
Action:
Finds the size of a file.
| Entry conditions:
|
| HL: | | Points to zero-terminated filename
|
| Exit conditions:
|
| c=1: | | HL=size in bytes
|
| c=0: | | Not found
|
FSIZEHANDLE - &B8BA
Action:
Finds the size of an open file.
| Entry conditions:
|
| DE: | | File handle
|
| Exit conditions:
|
| HL: | | Size in bytes
|
FTELL - &B8BD
Action:
Returns the value of the file pointer.
| Entry conditions:
|
| DE: | | File handle
|
| Exit conditions:
|
| HL: | | Current file position
|
FTESTEOF - &B8C0
Action:
Tests whether the end of a file has been reached.
| Entry conditions:
|
| DE: | | File handle
|
| Exit conditions:
|
| c=1: | | Not eor
|
| c=0: | | Eof
|
SELECTFILE - &B8C3
Action:
Displays the file selector (clearing the screen first), shows all files and allows a selection to be made
using the cursor keys and [Return]. In addition [Del->] and [<-Del] can be used to delete files.
An undocumented feature of this function is the ability to press [Shift][Ctrl][H] to override the effect
of the Hidden file attribute and make these files instantly visible. See FGETATTR (&B8CF)
for further details on attributes.
| Exit conditions:
|
| c=1: | | A file was selected ([Return] pressed), HL=filename
|
| c=0: | | [Stop] was pressed
|
SETDTA - &B8C6
Action:
Sets the memory block to be used by FINDFIRST (&B89C) and FINDNEXT (&B89F).
| Entry conditions:
|
| DE: | | Address of a 36-byte buffer which must be in common RAM (&8000h-&BFFF):
|
| Exit conditions:
|
| All registers preserved
|
FDATESTAMP - &B8C9
Action:
Sets a file's date and time to the current date and time.
| Entry conditions:
|
| HL: | | Zero-terminated filename
|
| Exit conditions:
|
| c=1: | | Succesful
|
| c=0: | | File not found
|
FGETATTR - &B8CF
Action:
Returns the attribute byte of a file.
| Entry conditions:
|
| HL: | | Zero-terminated filename
|
| Exit conditions:
|
| c=1: | | A=attribute
bit 0 = System (for in-built applications)
bit 1 = Hidden
bit 2 = Basic
bit 3 = Binary
bit 4 = Reserved
bit 5 = Reserved for internal use
bit 6 = Reserved
bit 7 = Reserved
|
| c=0: | | Not found
|
| HL: | | Preserved
|
System files are generally those created by the Diary, Address Bok and other in-built applications. They
are also generally saved as Hidden files except where the user needs to be able to select them.
Protext saves all files without any attributes so that they can be seen and selected by all applications.
This allows you to write programs in Protext, then enter BBC Basic and *EXEC them into memory - providing
an easier way of editing code.
All BBC Basic programs are saved with the Basic attribute set.
If the user has not configured the NC100 to display file dates and time via the System Setting menu, if a
file has the Basic attribute set, under BBC Basic SELECTFILE (&B8C3) will display it but
if the Hidden attribute is set, it will not. When not in BBC Basic, the Protext file selector will not display
files with a Basic or Hidden attribute, so you can hide selected files from non-BBC Basic applications.
However, if the user has elected to have file dates and times displayed, all files except those with a
Hidden attribute will be displayed whether in BBC Basic or not.
FSETATTR - &B8CC
Action:
Sets the attribute byte for a file opened for output. If the file is open for input only there is no effect.
| Entry conditions:
|
| DE: | | File handle
|
| C: | | Attribute byte
|
| Exit conditions:
|
| c=1: | | Successful
|
| c=0: | | File not found
|
KMGETYELLOW - &B8D2
Action:
Ascertains whether a Yellow event (so called because the [Function] key is coloured yellow) is pending.
A Yellow event occurs:
- When the user has pressed one of the [Function][Key] combinations that cause an immediate context
switch ([Function][Red], [Function][Green], [Function][Blue], [Function][Menu]), or
- When the machine is powerd up and (because the option to preserve context has not been set) needs to
return to the main menu.
| Exit conditions:
|
| c=1: | | BC=token if a Yellow event is pending. An application should exit as quickly as
possible, any saved files should be saved automaticly!
|
| c=0: | | BC=0 if no Yellow event is pending
|
NOTE: Each of the yellow event keys return the [Stop] token (&2FCh). An application should call
KMGETYELLOW (&B8D2) whenever an Escape key is read. This distinguishes between a Yellow
event and an ordinary Escape.
KMSETYELLOW - &B8D5
Action:
Sets up a Yellow event. Specialised use only.
| Entry conditions:
|
| BC: | | A yellow event token
|
| Exit conditions:
|
| All registers preserved
|
LAPCAT_RECEIVE - &B8D8
Action:
Reads a character from the parallel port using Lapcat protocol.
| Exit conditions:
|
| c=1: | | Successful, A=character
|
| c=0: | | No character read
|
LAPCAT_SEND - &B8DB
Action:
Sends a character to the parallel port using Lapcat protocol.
| Entry conditions:
|
| A: | | Character
|
| Exit conditions:
|
| c=1: | | Successful
|
| c=0: | | Error
|
PADGETVERSION - &B8DE
Action:
Gets the firmware version number.
| Exit conditions:
|
| HL: | | Version number (times 100). so, 1.03 returns 103
|