USING phrase

The USING phrase specifies the parameters that a program, method, or user-defined function receives when it is called or invoked. For function prototypes, the USING phrase specifies the parameters that will be used for conformance checking during function invocation.

The USING phrase is valid in the PROCEDURE DIVISION header of a called subprogram, invoked method entered at the beginning of the nondeclaratives portion, invoked user-defined function, or in the PROCEDURE DIVISION header of a function prototype definition. Each USING identifier must be defined as a level-01 or level-77 item in the LINKAGE SECTION of the called subprogram, invoked method, or invoked function.

Data items specified as arguments to user-defined function or function prototype invocations must follow the rules in Conformance of parameters for user-defined functions and function prototypes.

In a called subprogram entered at the first executable statement following an ENTRY statement, the USING phrase is valid in the ENTRY statement. Each USING identifier must be defined as a level-01 or level-77 item in the LINKAGE SECTION of the called subprogram.

However, a data item specified in the USING phrase of the CALL statement can be a data item of any level in the DATA DIVISION of the calling COBOL program, method, or function. A data item specified in the USING phrase of an INVOKE statement can be a data item of any level in the DATA DIVISION of the invoking COBOL program, method, or function. Likewise, a data item specified as an argument to a user-defined function invocation can be a data item of any level in the DATA DIVISION of the calling COBOL program, method, or function.

A data item in the USING phrase of the header can have a REDEFINES clause in its data description entry.

It is possible to call COBOL programs from non-COBOL programs or to pass user parameters from a system command to a COBOL main program. COBOL methods can be invoked only from Java™ or COBOL.

The order of appearance of USING identifiers in both calling and called subprograms, or invoking methods or programs and invoked methods, determines the correspondence of single sets of data available to both. The correspondence is positional and not by name. For calling and called subprograms, corresponding identifiers must contain the same number of bytes although their data descriptions need not be the same.

The order of appearance of arguments in a function invocation of a user-defined function or a function prototype, and USING identifiers in a function definition with the same name determines the correspondence of argument to formal parameter. That is, the order is positional and the first argument corresponds to the first formal parameter, etc. Each argument of a user-defined function or function prototype invocation must conform to each of its corresponding formal parameters according to the rules in Conformance of parameters for user-defined functions and function prototypes. The number of arguments must match the number of formal parameters.

For index-names, no correspondence is established. Index-names in a caller (that can be a program, method, or function) and index-names in a called routine (that can be a program, method, or function) always refer to separate indexes.

The identifiers specified in a CALL USING or INVOKE USING statement name the data items available to the calling program or invoking method or program that can be referred to in the called program or invoked method. These items can be defined in any DATA DIVISION section. Likewise, identifiers specified as arguments in a user-defined function invocation name the data items available to the calling program, method, or function that can be referred to in the invoked function. These items can also be defined in any DATA DIVISION section.

A given identifier can appear more than once in a USING phrase. The last value passed to it by a CALL statement, INVOKE statement, or user-defined function invocation is used.

The BY REFERENCE or BY VALUE phrase applies to all parameters that follow until overridden by another BY REFERENCE or BY VALUE phrase.

BY REFERENCE (for programs and methods)

When an argument is passed BY CONTENT or BY REFERENCE, BY REFERENCE must be specified or implied for the corresponding formal parameter on the PROCEDURE or ENTRY USING phrase.

BY REFERENCE is the default if neither BY REFERENCE nor BY VALUE is specified.

If the reference to the corresponding data item in the CALL statement declares the parameter to be passed BY REFERENCE (explicit or implicit), the program executes as if each reference to a USING identifier in the called subprogram is replaced by a reference to the corresponding USING identifier in the calling program.

If the reference to the corresponding data item in the CALL statement declares the parameter to be passed BY CONTENT, the value of the item is moved when the CALL statement is executed and placed into a system-defined storage item that possesses the attributes declared in the LINKAGE SECTION for data-name-1. The data description of each parameter in the BY CONTENT phrase of the CALL statement must be the same, meaning no conversion or extension or truncation, as the data description of the corresponding parameter in the USING phrase of the header.

BY REFERENCE (for functions only)

When an argument is received BY REFERENCE in a function definition, BY REFERENCE must be specified or implied for the corresponding formal parameter on the PROCEDURE DIVISION USING phrase.

To pass an argument effectively BY CONTENT on a user-defined function invocation, use the CONTENT-OF intrinsic function. For details about this intrinsic function, see CONTENT-OF. Also find an example in Passing arguments BY CONTENT to user-defined functions in the Enterprise COBOL Programming Guide.

BY REFERENCE is the default if neither BY REFERENCE nor BY VALUE is specified.

If the reference to the corresponding argument in the function invocation declares the parameter to be passed BY REFERENCE explicitly or implicitly, the program executes as if each reference to a USING identifier in the invoked function was replaced by a reference to the corresponding argument in the calling program, method, or function.

BY VALUE (for programs and methods)

When an argument is passed BY VALUE, the value of the argument is passed, not a reference to the sending data item. The receiving subprogram or method has access only to a temporary copy of the sending data item. Any modifications made to the formal parameters that correspond to an argument passed BY VALUE do not affect the argument.

Parameters specified in the USING phrase of a method procedure division header must be passed to the method BY VALUE.

See Passing data in the Enterprise COBOL Programming Guide for examples that illustrate these concepts.

BY VALUE (for functions only)

When an argument is received BY VALUE in a function definition, the value of the argument is passed, not a reference to the sending data item. The receiving function has access to only a temporary copy of the sending data item. Any modifications made to the formal parameters that correspond to an argument passed BY VALUE do not affect the argument in the invoking program, method, or function.

data-name-1

data-name-1 must be a level-01 or level-77 item in the LINKAGE SECTION.

When data-name-1 is an object reference in a method procedure division header, an explicit class-name must be specified in the data description entry for that object reference; that is, data-name-1 must not be a universal object reference.

For methods, the parameter data types are restricted to the data types that are interoperable between COBOL and Java, as listed in Interoperable data types for OO COBOL and Java.

Conformance of parameters for user-defined functions and function prototypes

In the following section, the argument of a user-defined function or function prototype invocation is considered the sending item, and the corresponding formal parameter defined in the function is considered the receiving item.

The number of arguments for a user-defined function or function prototype invocation must be the same as the number of formal parameters specified in the user-defined function definition.

If both an argument and its corresponding formal parameter are elementary items, the conformance rules for elementary items apply. Otherwise, the conformance rules for group items apply.

Group items

If either the sender or the receiver is an alphanumeric, national, or UTF-8 group item, and:

If the parameter is passed BY REFERENCE, then the formal parameter (the receiver) must be described with the same or fewer number of bytes as the corresponding argument (the sender). For variable-length data items such as those described with the OCCURS DEPENDING ON clause, the maximum length is used. No compile-time checking is done for unbounded groups.
Group items may not be passed BY VALUE.

Elementary items passed BY REFERENCE

For elementary items passed BY REFERENCE, the definition of the formal parameter and the definition of the argument must have the same BLANK WHEN ZERO, DYNAMIC LENGTH, JUSTIFIED, PICTURE, SIGN, and USAGE clauses, with the following exceptions:

Currency symbols match only if the corresponding currency strings are the same.
Period and comma picture symbols match only if the DECIMAL-POINT IS COMMA clause is in effect for both the calling program, method, or function and the invoked function, or for neither of them.

Elementary items passed BY VALUE

The formal parameter must be one of the following items:

Binary (USAGE BINARY, COMP, COMP-4, or COMP-5)
Floating point (USAGE COMP-1 or COMP-2)
Function-pointer (USAGE FUNCTION-POINTER)
Pointer (USAGE POINTER)
Procedure-pointer (USAGE PROCEDURE-POINTER)
One single-byte alphanumeric character (such as PIC X or PIC A)
One national character (PIC N) that is described as an elementary data item of category national

If the formal parameter is of class pointer, the conformance rules will be as if a SET statement were performed with the argument as the sending operand and the corresponding formal parameter as the receiving operand.

If the formal parameter is of class numeric, the conformance rules will be as if a COMPUTE statement were performed with the argument as the sending operand and the corresponding formal parameter as the receiving operand.

Otherwise, the conformance rules will be as if a MOVE statement were performed with the argument as the sending operand and the corresponding formal parameter as the receiving operand.