Technical Reference Manual - System Service Calls

Feel free to discuss any Organiser II related topic here
Post Reply
User avatar
Posts: 128
Joined: Wed Jan 27, 2021 3:44 pm

Technical Reference Manual - System Service Calls

Post by MartinReid »

Following on from Lostgallifreyan's statement "I used a system service call for editing in my EVENT logger" and MartinP's "I used the Technical Reference Manual" when I made the circuit schematic. While browsing the 'manual' I noticed these 'system services', for example...

Calculator: CA$ENTR
Provides an entry point to the calculator exactly like selecting CALC in the top-level menu.
This has a RED warning notice (I assume placed there by Dave, Jaap or Boris) not to call this routine from OPL "Do not call from OPL, since OPL is not re-entrant unless all its variables are preserved."

Does this mean other services can be called from OPL and if so how? For example...

Page 109 - XF$SORT (LZ only) - Sorts a file.

I have a bubble sort routine I use but it would be more compact if I could use this built in service.

Anyway any help anyone can give will be much appreciated.
Always sincere
User avatar
Posts: 27
Joined: Fri Jun 11, 2021 2:52 pm

Re: Technical Reference Manual - System Service Calls

Post by Lostgallifreyan »

About sorting, I'm not sure, and for compatibility it's maybe better to do a machine code tool that an XP or LZ can use equally well. From that standpoint, the first decision is whether to use a stable sort algorithm or not, because stable means if there are two CATs in a list, the first one is still first after sorting. The problem is that stable sort algorithms are slow. There is a way round this! Create a precursor substring, indexed 000, 001, etc BEFORE sorting, then do two fast sorts, one for the intended substring, then the second on these indexes where things are otherwise equal, then strip the indexes. It's awkward to code, but is stable, and faster than trying to build that stability into the search algorithm because any fast sort will do. Two fast ones is a lot faster than one stable one by conventional means.

NOTE: Bubble sort is stable but VERY slow, very primitive... Examine one called FastSort, it's not stable but is fast and usually easy enough to port to a system that hasn't already got it. One thing: Do NOT use any algorithm that uses recursion! You can usually avoid recursion by careful use of indexing in place, in a fixed size buffer. Recursion is dangerous, it eats memory, and in critical systems it's banned because it's too dangerous to trust because it can hose a system completely if it happens without strict limits. If an aerospace coder used it it might even be a sackable offence.. In systems as small as an Organiser it's wise to use practises used in 'embedded' systems.

About the calling from OPL, the risk must be assessed based on how variables are passed, i.e. by register, fixed address, or by stack. Stack is like the spare change holders once used on busses. A coin can be pushed on the stack, or popped off the top of it so the next one down is on top and accessible. Computer stacks are exactly similar in concept. The problem is that the WHOLE system uses one stack, so you have to make sure that anything you put there is removed before you hand it back to OPL. The same likely applies to registers. It's fairly easy to manage this for ANY call you make, you just have to make sure you do it and don't lose count of anything. TRAP errors WILL happen! Never try these games on a machine you can't commit solely to the experiment for the duration... Putting the code on a RAM pack is the best way, and there is a trick called a 'TRAP RAMpack' that can dump pack A onto a RAM pack in slot B if you really need to know what went wrong, but it's usually easier not to know, just code rigorously, then it won't happen anyway.

The thing to watch for in descriptions of system services is what they do to registers. Take note if anything says 'trashed', because that may mean you'd be wise to store whatever was in it and put it back after you call the thing that trashes it. :) Always consider the context, because that determines ultimately whether such details matter in practise. When it does matter, you can still call from OPL, but you call machine code you write that takes care of storing stuff that must be returned to registers, then that code calls the service, and on exit it puts stuff back as it found it, then RTS returns back to OPL which will be none the wiser if you did it right.
Post Reply