return length value in 64 bit (ileb) item lists to OpenVMS system services.

[Roger Tucker]

The programming concepts manual states in section 11.4.1, and I quote: "The item_list_64b form of an item list contains an additional quadword for the return length address field. The returned length is 64-bits." Also, the include file for C defines this field (ileb_64$pq_retlen_addr) as a long pointer to an unsigned _int64 value, so it seems like the return length address for a 64 bit item list should be 64 bits. But, the documenation in the "system services reference guide" under sys$getjpi(), sys$getdvi(), sys$getsyi(), sys$trnlnm(), etc. says and I quote "A quadword containing the user-supplied 64-bit address of a WORD in which $GETSYI writes the length in bytes of the information it actually returned" I capitalized WORD. I think the system service documentation is wrong. I tested this using getjpi() and getsyi(), and both clearly write a quadword into the return length address. Can someone verify this and get this to someone who can correct the documenation.

Also, the example program 4-5, in "Programming Concepts" using sys$getjpi() is wrong - the usersize should be unsigned short and the username[] field used in the printf() is not null terminated by getjpi().

[Robert Brooks_1 · Accepted solution]

Hmmm.

As the maintainer for $GETDVI, your note is of interest to me. However, it appears that $GETDVI does *not* support 64 bit item lists. In fact, the documentation in the V8.2 System Services Reference Manual for $GETDVI lists support for *only* the older, 32-bit variant (whose offsets are defined by ILEDEF in the language-dependent STARLET libraries and are prefixed by ILE3$). A quick check of the code for $GETDVI confirms that there is truly no support for 64-bit item lists.

Having said that, I will check the other services and request that the documentation be corrected for V8.3.

Thanks for the tip!

-- Rob

[John Gillings]

Roger,

The purpose of a 64 bit item list is to allow the items and returned length fields to be stored anywhere in 64bit address space P0, P2, P2, S0, S1, S2, so it's the addresses that need to be 64 bits. The objects they return aren't necessarily any bigger than they were for the 32 bit equivalent service.

So, if the service returns a WORD length field, that's all it returns. That the pointer to it is 4 times larger than the thing it points to is a bit odd, but that's just how it is. Don't confuse 64 bit addresses with 64 bit contents.

As Rob Brooks has pointed out, not all services support the 64 bit lists (yet?).

Documentation isn't always perfect. A report of errors or inconsistencies here is appreciated and *might* make it into engineering, but if you want to be sure your suggestions are acted on, please log a case with your local customer support centre.

[David Jones_21]

John Gillings: "So, if the service returns a WORD length field, that's all it returns. That the pointer to it is 4 times larger than the thing it points to is a bit odd, but that's just how it is. Don't confuse 64 bit addresses with 64 bit contents."

Careful reading of the original post makes it clear the poster wasn't confusing the pointer with what it points to. From day one in VMS, the return length pointer in an item list has been larger than the data cell it points to. In the 32-bit item list, no more than 16 bits for return length is needed because the largest return buffer it could specify is 65K. The new format has a 64-bit buffer length, so in the general case you need a octaword to hold all potential return length values.

[Roger Tucker]

Your right, looking at the documenation and 7.1 source code (the latest I have), getdvi() only supports 32 bit item lists.

getsyi() in routine putdata appears to write a 16 bit value to a 64 bit item list descriptor. I think this is a bug, although it does match the documentation.

getjpi() in routine $write_retlen checks for and writes a quadword return length address. This is the only get... system service that appears to handle 64 bit item lists with a 64 bit return length, but the documentation is wrong.

getlki() in routine movit appears to write a longword and the documenation is also correct. getlki() doesn't appear to allow 64 bit item lists.

getqui() doesn't support 64 bit item lists.
Documenation is correct.

So in summary, I could only find two system services that seem to support 64 bit item lists and they handle the return length address differently.

[Roger Tucker]

Forgot one, trnlnm() also appears to write a 64 bit return item length, but the documenation also says a word.