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:
CALL...BY REFERENCE identifier
Any changes made by the subprogram to the parameter affect the argument in the calling program.
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.
CALL...BY CONTENT ADDRESS OF data-item-name
CALL...BY CONTENT identifier
CALL...BY VALUE item
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.
CALL...RETURNING identifier
CALL...BY CONTENT literal
The called program cannot change the value of the literal.
CALL...BY CONTENT LENGTH OF identifier
The calling program passes the length of identifier from its LENGTH OF special register.
CALL 'ERRPROC' USING BY REFERENCE A BY CONTENT LENGTH OF A.
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.
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.
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.
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.
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
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, 2005. All Rights Reserved.