Robin Vowels wrote:
>On Tuesday, March 8, 2022 at 12:12:24 PM UTC+11, Thomas David Rivers wrote:
>
>
>>The IBM documentation for the ICLZ builtin says this:
>>
>>If the argument x is of the type SIGNED FIXED BIN(p) with p <= 15,
>>it is
>>converted to SIGNED FIXED BIN(31). If it is of the type UNSIGNED
>>FIXED BIN(p)
>>with p <= 16, it is converted to UNSIGNED FIXED BIN(32).
>>
>>So, in this example; I expect the argument 'k' to be converted to an
>>UNSIGNED FIXED BIN(32):
>>
>>test: proc options(main);
>>
>>dcl res fixed bin(31);
>>dcl k unsigned fixed bin(16);
>>
>>k = 1;
>>res = ICLZ(k);
>>display('RES is ' || res);
>>
>>end;
>>
>>And - thus, the result of the ICLZ on a value of X'1' with a 32-bit
>>integer parameter would be 31.
>>
>>
>.
>What? Why would it not be 1 ?
>.
>
>
>>However, when you execute this program, the result is 15 - which
>>indicates it's not being treated as an UNSIGNED FIXED BIN(32).
>>
>>
>.
>You haven't made it clear what you are doing.
>Your program should print the value 1.
>.
>
>
That is the entire program, and the output of the program is:
RES is 15
The ICLZ builtin function counts the number of leading zeros
in the underlying representation of the value; which depends on
the size of that representation.
The IBM documentation seems to, possibly, indicate that any value
represented by a datum smaller than a 4-byte integer is first converted
to a 4-byte
integer. Which means that the number of leading zeros in such a
representation
would be a value in the range 0 to 32 (although the count-leading-zeros
operation is
undefined for a zero value, and in some hardware, e.g. x86, returns
strange results,
so a careful program would check for a zero value, and the actual range
of the
count-leading-zeros operation should be considered to be 0 to 31.)
This program demonstrates that, contrary to the documentation, the compiler
is not converting the value to a 4-byte integer to determine the count
of leading zero bits
but is instead using the underlying represenation of the value, a 2-byte
integer.
In this case, an UNSIGNED FIXED BINARY value with a precision of 16 can
have an underlying representation of 2 bytes (16 bits.) A value of 1 would
then be in binary: 00000000 00000001 and thus have 15 leading zeros; hence
the result of 15.
Note that if the conversion to a FIXED BIN(31) had occured, as mentioned in
the documentation, the underlying representation would require 4 bytes
(32 bits) and
the result would be 31, not 15 (31 leading zero bits followed by a 1 bit.)
As to why one might wish to use the count-leading-zeros operation, I refer
you to the Wikipedia page that describes this and related operations and
their applications:
https://en.wikipedia.org/wiki/Find_first_set
As to the IBM documentation, the complete documentation on the ICLZ
builtin function can be found at the IBM web site, which you can arrive
at by
following this link:
https://www.ibm.com/docs/en/epfz/5.3?topic=subroutines-iclz
This is it, in its entirety (although re-formatted for posting):
ICLZ
Last Updated: 2021-09-08
ICLZ returns a FIXED BIN(31) value that indicates the number of
leading zeros in
a FIXED BIN value.
>>----- ICLZ( x ) ------ ><
x
Specifies a REAL FIXED BIN value with a scale factor of zero.
If the argument x is of the type SIGNED FIXED BIN(p) with p <= 15, it
is converted to
SIGNED FIXED BIN(31). If it is of the type UNSIGNED FIXED BIN(p) with
p <= 16, it is
converted to UNSIGNED FIXED BIN(32).
I did receive a reply from IBM regarding this, mentioning that they are
having
some difficulties responding to the thread. Their e-mail noted that the
documentation will be corrected to reflect the compiler's behavior.
So, this
is a documentation error.
I just wanted to answer Robin's questions, and put an end to this thread
for any future reader.