Passing data

You can choose among three ways of passing data between programs: BY REFERENCE, BY CONTENT, or BY VALUE.

About this task

BY REFERENCE: The subprogram refers to and processes the data items in the storage of the calling program rather than working on a copy of the data. BY REFERENCE is the assumed passing mechanism for a parameter if none of the three ways is specified or implied for the parameter.
BY CONTENT: The calling program passes only the contents of the literal or identifier. The called program cannot change the value of the literal or identifier in the calling program, even if it modifies the data item in which it received the literal or identifier.
BY VALUE: The calling program or method passes the value of the literal or identifier, not a reference to the sending data item. The called program or invoked method can change the parameter. However, because the subprogram or method has access only to a temporary copy of the sending data item, any change does not affect the argument in the calling program.

The following figure shows the differences in values passed BY REFERENCE, BY CONTENT, and BY VALUE:

This figure compares passing BY REFERENCE, BY CONTENT, and BY VALUE.

Determine which of these data-passing methods to use based on what you want your program to do with the data.

Table 1. **Methods for passing data in the CALL statement**
Code	Purpose	Comments
`CALL . . . BY REFERENCE` `identifier`	To have the definition of the argument of the `CALL` statement in the calling program and the definition of the parameter in the called program share the same memory	Any changes made by the subprogram to the parameter affect the argument in the calling program.
`CALL . . . BY REFERENCE ADDRESS OF` `identifier`	To pass the address of `identifier` to a called program, where `identifier` is an item in the `LINKAGE SECTION`	Any changes made by the subprogram to the address affect the address in the calling program.
`CALL . . . BY REFERENCE` `file-name`	To pass a data control block (DCB) to assembler programs	The file-name must reference a QSAM sequential file.¹
`CALL . . . BY CONTENT ADDRESS OF` `identifier`	To pass a copy of the address of `identifier` to a called program	Any changes to the copy of the address will not affect the address of `identifier`, but changes to `identifier` using the copy of the address will cause changes to `identifier`.
`CALL . . . BY CONTENT` `identifier`	To pass a copy of the identifier to the subprogram	Changes to the parameter by the subprogram will not affect the caller's identifier.
`CALL . . . BY CONTENT` `literal`	To pass a copy of a literal value to a called program
`CALL . . . BY CONTENT LENGTH OF` `identifier`	To pass a copy of the length of a data item	The calling program passes the length of the `identifier` from its `LENGTH` special register.
A combination of `BY REFERENCE` and `BY CONTENT` such as: `CALL 'ERRPROC' USING BY REFERENCE A BY CONTENT LENGTH OF A.`	To pass both a data item and a copy of its length to a subprogram
`CALL . . . BY VALUE` `identifier`	To pass data to a program, such as a C/C++ program, that uses `BY VALUE` parameter linkage conventions	A copy of the identifier is passed directly in the parameter list.
`CALL . . . BY VALUE` `literal`	To pass data to a program, such as a C/C++ program, that uses `BY VALUE` parameter linkage conventions	A copy of the literal is passed directly in the parameter list.
`CALL . . . BY VALUE ADDRESS OF` `identifier`	To pass the address of `identifier` to a called program. This is the recommended way to pass data to a C/C++ program that expects a pointer to the data.	Any changes to the copy of the address will not affect the address of `identifier`, but changes to `identifier` using the copy of the address will cause changes to `identifier`.
`CALL . . . RETURNING`	To call a C/C++ function with a function return value
File-names as `CALL` operands are allowed as an IBM® extension to COBOL. Any use of the extension generally depends on the specific internal implementation of the compiler. Control block field settings might change in future releases. Any changes made to the control block are the user's responsibility and are not supported by IBM.

Related concepts
Storage and its addressability

Related references
CALL statement (Enterprise COBOL for z/OS® Language Reference)
The USING phrase (Enterprise COBOL for z/OS Language Reference)
INVOKE statement (Enterprise COBOL for z/OS Language Reference)