ILE COBOL Programmer's Guide

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:

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

diagram showing linkage


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]