🚀 go-pugleaf

Warning: long article ahead

In <22023@usc.edu>, papa@pollux.usc.edu (Marco Papa) writes:
>In article <947@lpami.wimsey.bc.ca> lphillips@lpami.wimsey.bc.ca (Larry Phillips) writes:
>>In <9147@cbmvax.commodore.com>, peter@cbmvax.commodore.com (Peter Cherna) writes:
>>>WRONG!  Under no circumstances should you help yourself to a field that
>>>the system reserves for possible future use.  If we were to implement
>>>mutual exclusion using this field, yet you were using the field for
>>>your own implementation, how well do you think the two would co-exist?
>>>
>>>Not very well at all.
>>
>>Whoa!  That field is specified, in the latest includes I have, as being the
>>proper place to specify gadget mutual exclude. It is most definitely NOT
>>specified as being reserved, nor are there any warnings against using it as a
>>gadget mutual exclude field. While I fully realize that gadget mutual exclude
>>does not work in the current release, that is completely beside the point.
>
>Sorry, Larry, but here I have to agree with CBM. That field has been documented
>as "NOT IMPLEMENTED" from the first release of the AutoDocs, to the last one
>I have (the ones for 1.3).

Marco, that field has been documented as _not YET implemented_. From the very
beginning, the wording of the statements regarding it ahve varied between 'it
doesn't work in this release' to 'still not provided'. (para. 4.6.1, Readmes
for Intuituion on the ReadMe1.3 disk that is part of the 'Native Developer
Update disk set). The clear implication is that it was to be implemented in
some future release.

>  It has NEVER been listed for "private application
>use" as you (and the other guy) seem to imply it is.  The fact that it is
>not implemented, means that if you set it, that won't have any result
>with this release.

Oh, I see, you think I want to use it for something other than mutual exclusion
of gadgets, perhaps for storing phone numbers or something. I assure you that
what I want to do is to use it for its intended purpose, and to provide its
intended functionality within my own programs until such time as it is
implemented in the OS. I _know_ there is no result. That's the whole point. The
field has been provided, and it doesn't do what it should do. When any other
system function of structure flag doesn't do what I want it to do, I supply my
own code to make it do what I want. Is that A Bad Thing? I know it can be, but
it need not be. It all depends on the routine itself. If you think it is
automatically A Bad Thing to look at documented fields that are not marked
'private' or 'reserved' in a struct and to perform actions based upon the
contents, then I would ask you how you manage to write anything non-trivial at
all.

>>>The rule is simple:  Make sure all unused or reserved fields are properly
>>>initialized (normally to all zeros).
>>
>>Yes, the rule _is_ simple, but that field is NOT specified as unused or
>>reserved.  For the rule to work, it must work both ways.  You cannot reasonably
>>expect to leave fields lying around that are not marked as untouchable and just
>>sort of hope that nobody will use them.  
>
>CBM has always documented it as "reserved" for toggling gadgets at the
>"system" level, if and when they'll be implemented.  The fact that currently
>the use of the field is NOT imeplemented, does not give YOU the freedom
>to fool with it at will, and then expect that future releases will always
>work the same.

I don't see the word 'reserved' anywhere in the definition of MutualExclude.
Perhaps we are talking about two different things here. I see 'reserved' as
being "This field should be set to NULL, and not used for anything at all,
because we have put it here for future use, said use being undetermined at this
time'. Please feel free to correct me if I'm wrong on this.

The latest includes still say:

    /* by using the MutualExclude word, the appliprog can describe 
     * which gadgets mutually-exclude which other ones.  The bits 
     * in MutualExclude correspond to the gadgets in object containing 
     * the gadget list.  If this gadget is selected and a bit is set 
     * in this gadget's MutualExclude and the gadget corresponding to 
     * that bit is currently selected (e.g. bit 2 set and gadget 2 
     * is currently selected) that gadget must be unselected.  
     * Intuition does the visual unselecting (with checkmarks) and 
     * leaves it up to the program to unselect internally
     */
    LONG MutualExclude;  /* set bits mean this gadget excludes that gadget */

Now, I am not asking anyone to allow me to use this field as something
arbitrary. I am asking that CBM either implement the functionality as
documented, or to allow the user to do his own MutualExclude based upon the
contents of this DOCUMENTED field. Can you not see that user implemented MuEx
can be written in a perfectly transparent manner that will not interfere with
the system function should it ever be implemented? If CBM in fact decides not
to implement MuEx of gadgets, the very least they could do is change the docs
to say "if you see bits on in this field, your program should unselect the
corrsponding gadgets". If they do implement MuEx, the least they can do is to
leave this field alone so that those who are using it _FOR ITS INTENDED
PURPOSE_ will not end up with broken programs.

>  Most data structures (including Gadgets) have "user defined"
>fields at the end of them.  That's where you can fool with.  In any case it is
>very easy to build "custom user gadgets", with whatever additional fields 
>you want by creating your own modified structure:

Yes, all things are possible. It is not a matter of how many ways there are to
do it. It is a matter of what is being, or has been done, and the fact that at
least two other programmers have assumed that it is OK to use these bits in a
manner consistent with the documentation tells me that it is not altogether
unreasonable to think that there are more, and that they came to this
conclusion because of the documentation supplied by CBM.

>>Worse, you cannot reasonably specify a
>>field as being for a particular purpose and hope to defend yourself when
>>someone uses it for that purpose.
>
>using the MutualExclude field  according to "your own specification", since
>"no" specification from CBM exists (at the moment) is suicidal.  Especially
>when you've been warned.

I refer you (again) to the excerpt from the include file above, and restate
that the field does not do as I expect, that I wish to provide the
functionality in my own program, and that I wish to do so in a manner both
transparent and non-harmful to the system.

Where have I been warned? I have seen the 'not yet' and 'still not' implemented
statements. I have _NOT_ seen any warnings, dire or otherwise, saying that the
field might someday be changed to mean something else.

>>Do you reserve the right to make GRELBOTTOM suddenly mean GRELRIGHT, or to
>>change the call to OpenLibrary() to DoIO()?  Correctly written operating
>>systems do what the documentation says they do.  
>
>C'mon, larry. Give us a break.  GRELBOTTOM and OpenLibrary ARE documented.
>MutualExclude is not and has been reserved for future use.

Sorry, MutualExclude _IS_ documented. It is _ADDITIONALLY_ documented as 'not
yet implemented'. It is not documented as 'reserved', 'private', or 'do not
use'.

>>The proper thing to do in the case of this
>>particular bug is to either implement this field for its originally intended
>>purpose, leave it alone and let the authors use it for their own mutual exclude
>>routines, or to document it as being reserved, and wait a reasonable length of
>                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>>time (a few releases perhaps), before using it for something else.
> 
>If you were doing "serious" Amiga programming (i.e. if you had gotten the 
>AutoDocs from CBM as a certified or commercial developer), you would know
>that it IS reserved.

You were doing pretty good up until now. I resent your implication that my
programming is any less 'serious' than anyone else's. I AM a certified
developer. I DO have the autodocs from CBM. It is NOT documented as reserved.

>>All through the includes, one can find reserved and private fields. ROM
>>Stompers and Structure Twiddlers have been duly warned about the consequences
>>of messing with them. 'Proper Programmers' do not mess with them, but they
>>might be using a field DEFINED BY CBM to do what they see as perfectly
>							      ^^^^^^^^^
>>legitimate operations, fully within the letter and spirit of the documented
> ^^^^^^^^^^^^^^^^^^^^^
>>guidelines.
>
>Using a "system field" for user-defined operations is NOT a "legitimate"
>use of that field.  A comment like the one above really makes me wonder
>what kind of programmer you are.  You probably need a system liker MS-Windows,
>where you CAN'T see almost any system fields, so that you can't mess with them
>directly.

Oh? I suppose you are going to tell me I can't look at NextGadget to see if
there are any more in the list, and perform some perfectly valid, supported,
and documented function based upon the contents of that field?

And Marco, we can do without the ad hominem attacks and insults, thank you.
Please keep it on the level of a discussion of the pertinent points, or take it
to email.

>>This is not a flame... yet. It is a vehement plea for sanity. There are enough
>>programs out there already that purposely or inadvertently violate the rules.
>
>Really?  You're message promotes "insanity", IMHO. Programs that either
>purposely or inadvertently violate the "rules" should be BASHED as much as
>one can.  No prisoners taken :-)

No.. insanity is telling the programmer that something is not yet implemented,
implying that it will someday be implemented, and providing a perfectly good
place to allow an application program to transparently provide the service,
then decalring the function obsolete and changing the meaning of the field.

>-- Marco Papa 'Doc'
>-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
>"Xerox sues somebody for copying?" -- David Letterman
>-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=

-larry

--
" All I ask of my body is that it carry around my head."
         - Thomas Alva Edison -
+-----------------------------------------------------------------------+ 
|   //   Larry Phillips                                                 |
| \X/    lphillips@lpami.wimsey.bc.ca -or- uunet!van-bc!lpami!lphillips |
|        COMPUSERVE: 76703,4322  -or-  76703.4322@compuserve.com        |
+-----------------------------------------------------------------------+