Rational Developer for System z
COBOL for Windows, Version 7.5, Programming Guide


Passing data

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

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.

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

Table 71. 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 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  

related tasks
Describing arguments in the calling program
Describing parameters in the called program
Testing for OMITTED arguments
Specifying CALL . . . RETURNING
Sharing data by using the EXTERNAL clause
Sharing files between programs (external files)
Sharing data with Java

related references
CALL statement (COBOL for Windows Language Reference)
The USING phrase (COBOL for Windows Language Reference)
INVOKE statement (COBOL for Windows Language Reference)


Terms of use | Feedback

Copyright IBM Corporation 1996, 2008.
This information center is powered by Eclipse technology. (http://www.eclipse.org)