Path: utzoo!mnetor!uunet!lll-winken!lll-tis!ames!pasteur!ucbvax!hplabs!sdcrdcf!trwrb!aero!srt
From: srt@aero.ARPA (Scott R. Turner)
Newsgroups: comp.sys.apollo
Subject: Re: Need Help with gpr_$open_bitmap_file
Message-ID: <28975@aero.ARPA>
Date: 14 Apr 88 20:22:23 GMT
References: <880412.034912z.10599.srt@maui.cs.ucla.edu>
Reply-To: srt@aero.UUCP (Scott R. Turner)
Organization: The Aerospace Corporation, El Segundo, CA
Lines: 38

In article <srt@maui.cs.ucla.edu> srt@CS.UCLA.EDU (Scott Turner) writes:
>Anyone know how to use this godforsaken call to write a bitmap out to 
>a file and then restore it?  
>
>Incidentally, another fine example of Apollo documentation.

Thanks to everyone who sent help.  The problem turned out to be that
the bitmap file doesn't actually get written out (in the case of using
this call to create a bitmap file) until you explicitly deallocate the
appropriate bitmap descriptor.  

In general this is a badly conceived and badly documented call.

First, if you name something "open", a programmer naturally expects
corresponding "write", "read" and "close" functions, none of which
exist, and there is no indication in the documentation of the "open"
call what achieves these functions.

Second, there is confusion between opening/reading/writing/closing the
bitmap *file* and opening/reading/writing/closing the *bitmap*.  I
think the intent is to conceal the reading/writing of the *file* in
the reading/writing of the *bitmap*.  That is, gpr_$open_bitmap_file
returns a bitmap descriptor (an access structure for the *bitmap*) and
then reading/writing this *bitmap* has a concealed side-effect:
reading/writing the bitmap *file*.  In general, hidden side-effects of
this sort are a Bad Idea, and especially when there is a conceptual
confusion of the sort that exists here.  Many programmers might not
even realize the difference between the bitmap and the corresponding
file.

Finally, if you design a system where there isn't a specific ``close
and finish up I/O'' call, then the system should guarantee that the
actual state of the I/O matches the expected state by the next
possible check time.  If you write to an external bitmap file and the
documentation doesn't say you have to specifically close and update,
then the file should be kept in accordance with the current state as
maintained internal to the program.

						-- Scott Turner