%BINARY built-in function

The binary built-in function (%BINARY or %BIN) interprets the contents of a specified CL character variable as a signed binary integer.

The starting position begins at the position specified and continues for a length of 2 or 4 characters.

The syntax of the binary built-in function is shown in the following example:

%BINARY(character-variable-name starting-position length)

You can also code it like this example:

%BIN(character-variable-name starting-position length)

The starting position and length are optional. However, if the starting position and length are not specified, a starting position of 1 and length of the character variable that is specified are used. In that case, you must declare the length of the character variable as either 2 or 4.

If the starting position is specified, you must also specify a constant length of 2 or 4. The starting position must be a positive number equal to or greater than 1. If the sum of the starting position and the length is greater than the length of the character variable, an error occurs. (A CL decimal or integer variable may also be used for the starting position.)

You can use the binary built-in function with both the If (IF) and Change Variable (CHGVAR) commands. It can be used by itself or as part of an arithmetic or logical expression. You can also use the binary built-in function on any command parameter that is defined as numeric (TYPE of *DEC, *INT2, *INT4, *UINT2, or *UINT4) with EXPR(*YES).

When the binary built-in function is used with the condition (COND) parameter on the IF command or with the VALUE parameter on the Change Variable (CHGVAR) command, the contents of the character variable is interpreted as a binary-to-decimal conversion.

When the binary built-in function is used with the VAR parameter on the Change Variable (CHGVAR) command, the decimal value in the VALUE parameter is converted to a 2-byte or 4-byte signed binary integer and the result stored in the character variable at the starting position specified. Decimal fractions are truncated.

The system uses the binary built-in function on the RTNVAL parameter of the Call Bound Procedure (CALLPRC) command to indicate that the calling procedure expects the called procedure to return a signed binary integer.

A 2-byte character variable can hold signed binary integer values from -32 768 through 32 767. A 4-byte character variable can hold signed binary integer values from -2 147 483 648 through 2 147 483 647.

The following are examples of the binary built-in function:

```
DCL    VAR(&B2)  TYPE(*CHAR)  LEN(2)    VALUE(X'001C')
DCL    VAR(&N)   TYPE(*DEC)   LEN(3 0)
CHGVAR   &N   %BINARY(&B2)
```
The contents of variable &B2 is treated as a 2-byte signed binary integer and converted to its decimal equivalent of 28. It is then assigned to the decimal variable &N
```
DCL    VAR(&N)   TYPE(*DEC)   LEN(5 0)  VALUE(107)
DCL    VAR(&B4)  TYPE(*CHAR)  LEN(4)
CHGVAR   %BIN(&B4)    &N
```
The value of the decimal variable &N is converted to a 4-byte signed binary number and is placed in character variable &B4 Variable &B4 will have the value of X'0000006B'.
```
DCL    VAR(&P)  TYPE(*CHAR)  LEN(100)
DCL    VAR(&L)  TYPE(*DEC)   LEN(5 0)
CHGVAR   &L  VALUE(%BIN(&P 1 2) * 5)
```
The first two characters of variable &P is treated as a signed binary integer, converted to its decimal equivalent, and multiplied by 5. The product is assigned to the decimal variable &L.
```
DCL    VAR(&X)   TYPE(*CHAR)  LEN(50)
CHGVAR   %BINARY(&X 15 2)  VALUE(122.56)
```
The number 122.56 is truncated to the whole number 122 and is then converted to a 2-byte signed binary integer and is placed at positions 15 and 16 of the character variable &X. Positions 15 and 16 of variable &X will contain the hexadecimal equivalent of X'007A'.
```
DCL    VAR(&B4)  TYPE(*CHAR)  LEN(4)
CHGVAR   %BIN(&B4)  VALUE(-57)
```
The value -57 is converted to a 4-byte signed binary integer and assigned to the character variable &B4. The variable &B4 will then contain the value X'FFFFFFC7'.
```
DCL    VAR(&B2)  TYPE(*CHAR)  LEN(2)   VALUE(X'FF1B')
DCL    VAR(&C5)  TYPE(*CHAR)  LEN(5)
CHGVAR   &C5  %BINARY(&B2)
```
The contents of variable &B2 is treated as a 2-byte signed binary integer and converted to its decimal equivalent of -229. The number is converted to character form and stored in the variable character &C5. The character variable &C5 will then contain the value '-0229'.
```
DCL    VAR(&C5)  TYPE(*CHAR)  LEN(5)   VALUE(' 1253')
DCL    VAR(&B2)  TYPE(*CHAR)  LEN(2)
CHGVAR   %BINARY(&B2)  VALUE(&C5)
```
The character number 1253 in character variable &C5 is converted to a decimal number. The decimal number 1253 is then converted to a 2-byte signed binary integer and stored in the variable &B2. The variable &B2 will then have the value X'04E5'.
```
DCL    VAR(&S)  TYPE(*CHAR)  LEN(100)
IF     (%BIN(&S 1 2) *GT 10)
       THEN( SNDPGMMSG MSG('Too many in list.') )
```
The first 2 bytes of the character variable &S are treated as a signed binary integer when compared to the number 10. If the binary number has a value larger than 10, then the Send Program Message (SNDPGMMSG) command is run.

DCL    VAR(&RTNV) TYPE(*CHAR) LEN(4)
CALLPRC PRC(PROCA) RTNVAL(%BIN(&RTNV 1 4))

Procedure PROCA returns a 4-byte integer which is stored in variable &RTNV.