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.Link to detail.

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.1
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  
  1. 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)