Conference noted::hackers_v1

616.0. "The Doctor is In" by OWL::GUILLERMO (It's a strange world isn't it?) Wed Dec 02 1987 13:44

    	...You see Doctor, it began when I was an infant...
    Oh, I don't mean that _literally_ ... I mean before I was literate
    in computers; infancy in knowledge. What a cruel paradox ! To
    realize the more learned, the more unknown...
    
    	But I have spent half a lifetime 'learning' to adjust to that
    concept about learning. And like early inculcated lessons of life which
    have proven to have complements and mitigating factors and contradictions,
    so does computer documentation. Now, I have misinterpreted messages
    sometimes to my embarrassment (why ?), misinterpreting the obvious.
    But isn't it possible...could there be the slightest chance that
    some documentation was intentionally written in an ambiguous, esoteric
    style, or am I just being paranoid ?
    
    	I suppose the problem starts when sites upgrade their operating
    systems in exponential ratios to the available documentation, so
    that cross-referencing a Callable DECspell software spec to "Guide to
    Creating Modular Procedures on VAX/VMS" becomes impossible.
    
    	But what do I do with parameters described as "ret_status.wlc.v",
    "corrector_flag.rbu.r" ? Is a "binary mask" something that can turn
    off or on your face ? And this "mask" can be defined as "mask bits"
    to which you can assign a value of 1 or 0 ?
    
    	If I had 7 condition codes available to me defined in a shareable
    library, would I need 7 definitions in COBOL working-storage with
    a "value is external" clause and 7 "by value" clauses for each of
    those return status codes ? Would it help if I could believe what
    I read ? But Doctor, not only have I been _told_ not to do that;
    I can even cite situations where what I read was WRONG ! And there's
    more Doctor...
    
    	...excuse me ? You say, that's what I'm paid for ? And because
    I've come to see you, that's how you get paid...and the cycle of
    harmony in the universe remains unbroken...yes, yes...I see it all
    now...
    

           What a difference a morning makes. I brought myself to consult
    an oracle (usually unavailable) and here's what he told me:
    
    	o	Condition codes don't necessarily have to agree in number
    		or specification as documented. If linking an .OLB as
    		as opposed to an .EXE, you can obtain a listing of said
    		codes via the following macro:
    
    		.TITLE PQLDEF
    		$PQLDEF GLOBAL
    		.END
    
    		This is documented in some obscure place in the Runtime
    		Library Procedures manual.
        
	o	The notation suffix on parameters is a standard (!)
    		mode of documentation signifying usage and description
    		of the parameter. This is also supposed to be documented
    		someplace. (w - working-storage? l - longword ? .v -
    		passed by value ?)
    
    	o	"Binary Mask" is a word integer value that corresponds
    		to the sum of the decimal values provided for the condition
		codes to be checked.

    	o	I figured out for myself, after some consideration that
    		I need only accept a return status once in the call,
    		then compare that value to the 7 defined for equivalence.
    
    	It's unravelling. Stay tuned...