What does BINARY(4) mean in API documentation?

BINARY(4) means a 4-byte binary number.

In RPG III, this means a subfield of a data structure that is defined with 4 bytes, and has the 'B' type.

In RPG IV, there are two kinds of 4-byte binary number: the 10-digit integer or the 9-digit binary. The 10-digit integer is better when dealing with APIs.

If you define an integer or binary number using length notation (no from-position), you give the number of digits. 10I-0 or 9B-0.

A very common error is to define a BINARY(4) field or parameter using length notation as 4B-0. This always causes problems calling the API.

---

Why does RPG's 'binary 4' drop the high-order digit?

Well, RPG's 'binary' data type does not support the full range of numbers possible in a binary number.

Maybe I need to back up. A binary number (in the sense that the manual uses the word binary) is one whereby each binary digit is used to represent a numeric value in increasing powers of two. So, a 2 digit binary number can hold numeric values as high(!) as 4:

2 (binary) to the 2nd power(two digits) = 4.

An 8 digit binary number can hold numeric values as high as 2^8, or 256. A two byte binary number has 16 bits (digits) so it can hold numeric values as high as 2^16, or 65536. (I'm ignoring the sign for this discussion.)

An RPG 'binary' data type can be two bytes or four.

Sneaking a peek at the RPG Reference, Chapter 10 (Data types) we can see that the 2 byte 'binary' gets defined with a length of 4.

From the manual

Every input field read in binary format is assigned a field length (number of
digits) by the compiler. A length of 4 is assigned to a 2-byte binary field; a length
of 9 is assigned to a 4-byte binary field, if the field is not defined elsewhere in the
program. 

Because of these length restrictions, the highest decimal value that can be
assigned to a 2-byte binary field is 9999 and the highest decimal value that can be
assigned to a 4-byte binary field is 999 999 999.

Theoretically a two byte field should be able to hold a value up to 65536 as described above. But with length 4, we can only store up to 9999! That high-order digit simply can't be stored in a 4 digit field.

An RPG 'integer' data type is a Real, True, Honest implementation of the binary data format (as laid out in the RPG Reference.) 'Integer' includes interpreting the highest-order bit as the sign, so a two byte integer actually can hold values between -32767 and +32767 (2^15=32768). The 'unsigned' data type is what I was describing above.

---

Also, see Barbara's excellent article on converting C prototypes to RPG at http://www.opensource400.org/callc.html