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 OF special 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 the data item on the CALL...BY
REFERENCE or CALL...BY CONTENT statement. For example:
CALL...BY REFERENCE OMITTED
CALL...BY CONTENT 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.
Describing Arguments in the Calling Program

The data that is passed from a calling program is called an argument. In the calling program, the arguments are
described in the Data Division in the same manner as other data items in the Data Division. Unless they are in the
Linkage Section, storage is allocated for these items in the calling program. If you reference data in a file, the file must
be open when the data is referenced. Code the USING clause of the CALL statement to pass the arguments.
Describing Parameters in the Called Program

The data that is received in a called program is called a parameter. In the called program, parameters are described in
the Linkage Section. Code the USING clause after the PROCEDURE-DIVISION header to receive the parameters.
Writing the Linkage Section in the Called Program

You must know what is being passed from the calling program and set up the Linkage Section in the called program to
accept it. To the called program, it doesn't matter which clause of the CALL statement you use to pass the data (BY
REFERENCE, BY VALUE or BY CONTENT). In all cases, the called program must describe the data it is receiving. It
does this in the Linkage Section.
The number of data-names in the identifier list of a called program should not be greater than the number of
data-names in the identifier list of the calling program. There is a one-to-one positional correspondence; that is,
the first identifier of the calling program is passed to the first identifier of the called program, and so forth. The
ILE COBOL compiler does not enforce consistency in terms of number of arguments and number of parameters nor
does it enforce consistency in terms of type and size between an argument and its corresponding parameter.

Any inconsistencies in terms of number of arguments and number of parameters may result in runtime exceptions. For
a dynamic program call, when the number of arguments is greater than the number of parameters, a runtime exception
is generated in the calling program when the CALL statement is attempted. This exception can be captured if the ON
EXCEPTION phrase is specified on the CALL statement.
When the number of arguments is less than the number of parameters, a runtime exception is not generated in the
calling program when the CALL statement is performed. Instead, a pointer exception is generated in the called program
when it tries to access an unsupplied parameter.
If an argument was passed BY VALUE, the PROCEDURE DIVISION header of the subprogram must indicate that:
PROCEDURE DIVISION USING BY VALUE DATA-ITEM.
If an argument was passed BY REFERENCE or BY CONTENT, the PROCEDURE DIVISION header does not need to
indicate how the argument was passed. The header can either be:
PROCEDURE DIVISION USING DATA-ITEM
or:
PROCEDURE DIVISION USING BY REFERENCE DATA-ITEM
Grouping Data to be Passed

Consider grouping all the data items you want to pass between programs and putting them under one level-01 item. If
you do this, you can pass a single level-01 record between programs. For an example of this method, see Figure 58.
To make the possibility of mismatched records even smaller, put the level-01 record in a copy member, and copy it in
both programs. (That is, copy it in the Working-Storage Section of the calling program and in the Linkage Section of the
called program.)
Figure 58. Common Data Items in Subprogram Linkage

(C) Copyright IBM Corporation 1992, 2006. All Rights Reserved.