From: Uwe Zessin [zessin@my-deja.com]
Sent: Thursday, July 01, 1999 2:19 PM
To: Info-VAX@Mvb.Saic.Com
Subject: Has VMS engineering forgotten about the 'returned length
address'?

People, I'm angry with you!

Can you imagine that I wasted a lot of time with debugging
just because you don't bother to fill in returned lengths
for output items ?!

The first time (SJC$_ENTRY_NUMBER_OUTPUT) I caught this by
pure luck. This is part of a bigger package that creates
and processes item lists 'on the fly' what makes debugging
somewhat hard. A check that traps division-by-zero attempts
told me that the 'returned length' was still 0.
    (I don't want to leave ships dead in the water ;-)

OK, no big deal, $SNDJBC has only 2 output items and one of
them does not bother to set the returned length. Create a
small workaround and be set. NOT!

An enhancement to my software and a number of QUI$_ output items
joined the club! Well, OK. I enhanced the workaround for the
enhancement and thought that was it. NOT!

I now work with SYS$GET_SECURITY() and it even gets WORSE!
The returned length is not only missing for integer (byte, word,
long- and quadwords) items, no, it is also missing for ACEs -
I have just debugged that with OSS$_ACL_READ_ENTRY.

I now have to create _another_ workaround to pick the ACE's
length from the buffer, just because you don't bother to
put it's length into the specified address. Before you ask:
yes - the 'returned length address' _IS_ provided, has been
since a long time.
                    ---

And while I have your attention:
The documentation for SYS$GET_SECURITY() is one of the worst
I encountered so far.

Example:  OSS$_ACL_FIND_NEXT
  "When you specify OSS$_ACL_FIND_NEXT, $GET_SECURITY advances
  the current position to the next ACE in the ACL."

That's all. Nice. How do I set the item up ?  Is it just a
boolean item code like INIT$_HIGHWATER for SYS$INIT_VOL() ?
Or do I have to specify a buffer (byte, word, longword, ?)
and put a 1 in it? What do I have to put into the word
holding the buffer length of this item?
Did the person writing the documentation expect us to use
'try and error' to find it out?

Or: OSS$_ACL_READ
  "When you specify OSS$_ACL_READ, $GET_SECURITY returns the
  portion of the object's ACL to the buffer pointed to by
  the buffer address."

Ahh, yes. And what is the format? I guess I have to use
OSS$_ACL_LENGTH or can I just go over all ACEs and stop
at a 0-length byte (if there is one)? What happens when
the buffer is too small? What does it mean by 'portion'?
Do I have to guess again? Run another experiment?

This is highly critical stuff and from a short look
I can tell that the documentation for SYS$SET_SECURITY()
isn't better ...
                       ---

I have tested the code on OpenVMS VAX V6.1 and I have
looked in its documentation and the V7.2-EFT3 kit that
I just had at hand.
                       ---

Andy G., can I have the list of responsible engineers? In
the meantime I'm going to look for a 'large heavy object'
myself ;-)

--
Uwe Zessin


Sent via Deja.com http://www.deja.com/
Share what you know. Learn what you don't.