oswordreadclock_utc

[Tony van der Hoff]

On 7 Jul 2001, David J. Ruck <druck at freeuk.com> wrote:

> Hi,
> 
> I've been plagued by an obscure bug in the developemnt version of
> DiscKnight for a month now, its been hell of a job tracking it down, as it
> occurred in random addresses in the SharedCLibrary, left no stack back
> trace, only occurred with certain datasets, and didn't occur when built
> with memory checking or debug data.
> 
Ouch! Very nasty; I'm really sorry you've experienced such problems ;-(

[snip]
> 
> My question is, should oswordreadclock_utc and its related functions
> xoswordreadclock_local_string, xoswordreadclock_local_bcd,
> xoswordreadclock_convert_bcd_to_string and the equivelent write clock
> functions set up the reason code in the block themselves? 
> 
They are presently not intended to, although I agree that this might be a
desirable feature. The problem is that, at present, DefMod has no way of
initialising data structures (as opposed to registers). The OSLib veneer is
simply too thin to handle such concepts. The user is expected to supply any
data structure fully initialised.

> I assumed that as each is an individual named function to perform the
> specific operation, that with no documentation in headers or StrongHelp
> manuals to say their entry conditions required the block to be initialised,
> the reason code would be inserted by the function. Does anyone else agree?

I certainly agree, but don't really see where it would be appropriate to
describe this behaviour in the Stronghelp manual, or the C headers. You have
made a reasonable, but incorrect, assumption about OSLib behaviour. An
unhelpful response might be that nowhere in the documentation does it say
that OSLib *does* initialise parameter blocks ;-). The reason for having
individually named functions is in order to differentiate the various
parameter block structures.

> Are there any other similar functions where this does or does not occur?
> 
You must initialise any parameter block where a SWI requires this.
This is no different from calling the raw SWI. Nowhere in OSLib is this done
for you, nor has it the ability to do so.

The next question is whether or not we should change this behaviour. OSLib is
designed as a very thin (therefore fast) veneer over the API. I'm not certain
that adding this sort of extra functionality is necessary or desirable; it
will add at least one (depending on the data value) instruction to each
veneer so affected. 

I don't think there are many instances in the API such as this, where a
parameter block can be initialised with one or more constants. For instance,
opening the PRM at random gave me Wimp_GetWindowOutline, where a window
handle is passed in the parameter block. This is obviously not a candidate
for a build-time constant, but the requirement for initialisation still
exists. Might it confuse the user if we initialised some things, but not
others? 

My present feeling is that whilst it would be nice to get OSLib to do this
initialisation where possible, the number of applicable API calls, and
therefore the potential benefits of doing this, is very limited. They are
mostly OS_Word and OS_Byte calls, which are gradually being superseded in any
case. I wonder whether it might not be better to hive this sort of
functionality off to OSLibSupport, rather build it into the core library.

Whilst not a valid reason for not changing things, I must confess I have no
idea as to how to change DefMod to accommodate this, although I've not looked
into it very deeply, it is certainly not trivial. Perhaps more knowledgable
DefMod experts than myself can comment? If there is enough support, and no
serious objections for such a change, I'm quite happy to see what can be
done. Naturally, any other comments are most welcome.

-- 
Tony van der Hoff         | MailTo:tony at mk-net.demon.co.uk
                          | MailTo:avanderhoff at iee.org
Buckinghamshire, England  | http:www.mk-net.demon.co.uk