Passing Data Using CALL…BY REFERENCE, BY VALUE, or BY CONTENT

BY REFERENCE means that any changes made by the subprogram to the variables it received are visible by the calling program.

BY CONTENT means that the calling program is passing only the contents of the literal or identifier. With a CALL…BY CONTENT, the called program cannot change the value of the literal or identifier in the calling program, even if it modifies the parameters it received.

BY VALUE means that the calling program is passing the value of the literal, or identifier, not a reference to the sending item. The called program can change the parameter in the called program. However, because the subprogram has access only to a temporary copy of the sending item, those changes don't affect the argument in the calling program.

Whether you pass data items BY REFERENCE, BY VALUE, or BY CONTENT depends on what you want your program to do with the data:

If you want the definition of the argument of the CALL statement in the calling program and the definition of the parameter in the called program to share the same memory, specify:
```
CALL…BY REFERENCE identifier
```
Any changes made by the subprogram to the parameter affect the argument in the calling program.
If you want to pass the address of a record area to a called program, specify:
```
CALL…BY REFERENCE ADDRESS OF record-name
```
The subprogram receives the ADDRESS OF special register for the record-name you specify.

You must define the record name as a level-01 or level-77 item in the Linkage Section of the called and calling programs. A separate ADDRESS OF special register is provided for each record in the Linkage Section.
If you want to pass the address of any data item in the DATA DIVISION to a called program, specify:
```
CALL…BY CONTENT ADDRESS OF data-item-name
```
If you do not want the definition of the argument of the CALL statement in the calling program and the definition of the parameter in the called subprogram to share the same memory, specify:
```
CALL…BY CONTENT identifier
```
If you want to pass data to ILE programs that require BY VALUE parameters use:
```
CALL…BY VALUE item
```
If you want to pass a numeric integer of various lengths specify:
```
CALL…BY VALUE integer-1 SIZE integer-2
```
The numeric integer is passed as a binary value of length integer-2. The SIZE phrase is optional. If not specified, integer-1 is passed as a 4 byte binary number.
If you want to call an ILE C, C++ or RPG function with a function return value, use:
```
CALL…RETURNING identifier
```
If you want to pass a literal value to a called program, specify:
```
CALL…BY CONTENT literal
```
The called program cannot change the value of the literal.
If you want to pass the length of a data item, specify:
```
CALL…BY CONTENT LENGTH OF identifier
```
The calling program passes the length of identifier from its LENGTH OFspecial register.
If you want to pass both a data item and its length to a subprogram, specify a combination of BY REFERENCE and BY CONTENT. For example:
```
CALL 'ERRPROC' USING BY REFERENCE A
     BY CONTENT LENGTH OF A.
```
If you do not want the called program to receive a corresponding argument or if you want the called program to use the default value for the argument, specify the OMITTED phrase in place of each data item to be omitted on the CALL…BY REFERENCE or CALL…BY CONTENT statement. For example:
```
CALL…BY REFERENCE OMITTED
CALL…BY CONTENT OMITTED OMITTED
```
In the called program, you can use the CEETSTA API to determine if a specified parameter is OMITTED or not.
If you want to pass data items with operational descriptors, specify the LINKAGE TYPE IS PRC…USING ALL DESCRIBED clause in the SPECIAL-NAMES paragraph. Then use the CALL…BY REFERENCE, CALL…BY CONTENT or CALL…BY VALUE statement to pass the data. Operational descriptors provide descriptive information to the called ILE procedure in cases where the called ILE procedure cannot precisely anticipate the form of the data items being passed. You use operational descriptors when they are expected by a called ILE procedure written in a different ILE language and when they are expected by an ILE bindable API. Refer to the ILE Concepts book for more information about operational descriptors. For example:
```
SPECIAL-NAMES.  LINKAGE TYPE PRC FOR 'ERRPROC'
                USING ALL DESCRIBED.
               ⋮
CALL 'ERRPROC' USING BY REFERENCE identifier.
```
or
```
SPECIAL-NAMES.  LINKAGE TYPE PRC FOR 'ERRPROC'
                USING ALL DESCRIBED.
                ⋮
CALL 'ERRPROC' USING BY CONTENT identifier.
```

Data items in a calling program can be described in the Linkage Section of all the programs it calls directly or indirectly. In this case, storage for these items is allocated in the outermost calling program.