CALL Statement specifications COBOL

The CALL statement causes control to be transferred from one object program to another, within the run unit.

Format 1:Call…On Overflow

Call…On Overflow

Format 2:Call…On Exception

Call…On Exception

The execution of a CALL statement causes control to pass to the program whose name is specified by the value of literal-1 or identifier-1, termed the “called” program.The program in which the CALL statement appears is the “calling” program.

literal-1 must be a nonnumeric literal.

identifier-1 must be defined as an alphanumeric data item such that its value can be a program-name.

The value of literal-1 or of the data item referenced by identifier-1 specifies a program-name that is used to select a program for loading and execution.If the program being called is a COBOL program, the program that is loaded and executed may be selected because the program-name matches the program-name that appears in the PROGRAM-ID paragraph of the called program.For this comparison, any trailing spaces are ignored.Other techniques that are available for selecting the called program are dependent on the runtime operating system, and are, therefore, described in the RM/COBOL User’s Guide.

Called programs may contain CALL statements.However, a called program must not contain a CALL statement that directly or indirectly calls the calling program.If a CALL statement is executed within the range of a declarative, that CALL statement cannot directly or indirectly reference any called program to which control has been transferred and which has not completed execution.

The CALL statement may appear anywhere within a segmented program.When a CALL statement appears in a section with a segment-number greater than or equal to 50, that segment is in its last used state when the EXIT PROGRAM statement returns control to the calling program.

Two or more programs in the run unit may have the same program-name, and the reference in a CALL statement to such a program-name is resolved by using the scope of names conventions for program-names.

For example, when only two programs in the run unit have the same name as that specified in a CALL statement:

  1. One of those two programs must also be contained directly or indirectly either within the separately compiled program which includes that CALL statement or within the separately compiled program which itself directly or indirectly contains the program which includes that CALL statement.
  2. The other of those two programs must be a different separately compiled program.

The mechanism used in this example is as follows:

  1. If one of the two programs having the same name as that specified in the CALL statement is directly contained within the program which includes that CALL statement, that program is called.
  2. If one of the two programs having the same name as that specified in the CALL statement possesses the common attribute and is directly contained within another program which directly or indirectly contains the program which includes the CALL statement, that common program is called unless the calling program is contained within that common program.
  3. Otherwise, the separately compiled program is called.

If the called program does not possess the initial attribute, it and each program directly or indirectly contained within it, is in its initial state the first time it is called within a run unit and the first time it is called after a CANCEL to the called program.

On all other entries into the called program, the state of the program and each program directly or indirectly contained within it remains unchanged from its state when last exited.

If the called program possesses the initial attribute, it and each program directly or indirectly contained within it, is placed into its initial state every time the called program is called within a run unit.

Files associated with the internal file connectors of a called program are not in the open mode when the program is in an initial state.

On all other entries into the called program, the states and positioning of all such files is the same as when the called program was last exited.

The process of calling a program or exiting from a called program does not alter the status or positioning of a file associated with any external file connector.

USING Phrase

USING Phrase

The operands specified by the USING phrase of the CALL statement indicate those data items available to a calling program that may be referred to in the called program.The order of appearance of the operands in the USING phrase of the CALL statement and the USING phrase in the Procedure Division header is critical.Corresponding operands refer to a single set of data that is available to the called and calling programs.The correspondence is by position, not name.Index-names cannot be made available to the calling program.Index-names in the called and calling programs always refer to separate indexes, except for index-names with the external attribute.

The USING phrase is included in the CALL statement only if there is a USING phrase in the Procedure Division header of the called program.The number of operands in the two USING phrases need not be the same.However, when the two lists have a different number of operands, trailing operands for which there is no corresponding operand in the other list are inaccessible to the called program.

The reserved word OMITTED may be specified to represent an inaccessible operand in the list of operands in the USING phrase of the CALL statement.

In the called program, operands that are inaccessible, either because of omitted trailing operands or use of the word OMITTED in the USING phrase of the CALL statement in the calling program, have a null address.If the called program refers to an inaccessible argument, other than with the ADDRESS special register or in the USING or GIVING phrase of a CALL statement, a data reference error will occur.The called program can check for inaccessible operands by using the ADDRESS special register to test the address of the actual argument for equality to the figurative constant NULL.

Each operand in the USING phrase must have been defined as a data item in the File Section, Working-Storage Section, Communication Section or Linkage Section, and must be a level 01 data item, a level 77 data item, or an elementary data item.

The values of the parameters referenced in the USING phrase of the CALL statement are made available to the called program at the time the CALL statement is executed.

Both the BY CONTENT and BY REFERENCE phrases are transitive across the parameters that follow them until another BY CONTENT or BY REFERENCE phrase is encountered.If neither the BY CONTENT nor the BY REFERENCE phrase is specified prior to the first parameter, the BY REFERENCE phrase is assumed for identifiers and the BY CONTENT phrase is assumed for literals.

Note:Prior to v7.5 of RM/COBOL, both identifiers and literals were passed BY REFERENCE when neither the BY CONTENT nor the BY REFERENCE phrase had been explicitly specified.A configuration option has been added to retain the prior behavior; see the SUPPRESS-LITERAL-BY-CONTENT keyword of the COMPILER-OPTIONS configuration record in the RM/COBOL User’s Guide.

If the BY REFERENCE phrase is either specified or implied for an operand in the USING list, the object program operates as if the associated data item in the called program occupies the same storage area as the corresponding data item in the calling program.The description of the data item in the called program must describe the same number of character positions as described by the corresponding item in the calling program.

If the BY CONTENT phrase is specified or implied for a parameter, the called program cannot change the value of this parameter as referenced in the USING phrase of the CALL statement, though the called program may change the value of the data item referenced by the corresponding data-name in the Procedure Division header of the called program.The data description of each parameter in the BY CONTENT phrase of the CALL statement must be the same (that is, no conversion, extension or truncation) as the data description of the corresponding parameter in the USING phrase of the Procedure Division header.

When the ADDRESS special register is specified in the USING phrase, the result value is always passed by content.The base address of a level 01 or 77 Linkage Section item can only be changed by Formats 5 and 6 of the SET statement.Thus, if the goal is to change the address of a Linkage Section item based on an argument value, the calling program must pass by reference a pointer data item as an argument.The called program may then modify the value of this pointer data item argument.The calling program may then use the pointer data item after the CALL statement in a Format 5 SET statement to set the address of the Linkage Section item.

When an identifier that refers to a level-number 01 or 77 Linkage Section data item that represents a formal argument is specified in the USING phrase of a CALL statement, the data item is resolved according to its description in the calling program. This is an exception to the rule that formal arguments are resolved according to their description in the Linkage Section of the called program.How the data item is resolved mainly affects the length of the data item as seen in the called program.See the “Linkage Section” topic, for additional information on this special case of resolving Linkage Section record-names.

GIVING phrase

GIVING phrase

RETURNING is a synonym for GIVING.

The operand specified in the GIVING phrase of the CALL statement indicates a data item available to a calling program that may be referred to in the called program for purposes of returning a result from the called program.The GIVING argument is functionally the same as any of the USING arguments, except that BY CONTENT and OMITTED are not allowed.The purpose of the GIVING phrase is for source program readability by indicating the return value argument.

The GIVING phrase is included in the CALL statement only if there is a GIVING phrase in the Procedure Division header of the called program.If the GIVING phrase is omitted in the CALL statement when calling a program that includes the GIVING phrase in the Procedure Division header, then the GIVING operand is inaccessible to the called program.If the GIVING phrase is included in a CALL statement where the GIVING phrase is not included in the Procedure Division header of the called program, it has no effect and is ignored.In this case, the operand of the GIVING phrase in the calling program is unchanged after the called program completes.

The ADDRESS special register may not be specified in the GIVING phrase, but an identifier that refers to a pointer data item may be specified.

When an identifier that refers to a level-number 01 or 77 Linkage Section data item that represents a formal argument is specified in the GIVING phrase of a CALL statement, the data item is resolved according to its description in the calling program. This is an exception to the rule that formal arguments are resolved according to their description in the Linkage Section of the called program.

OVERFLOW, EXCEPTION, and NOT EXCEPTION Phrases

ON OVERFLOWimperative –statement -1

ON EXCEPTIONimperative –statement -1

NOT ON EXCEPTIONimperative –statement -2

If, when a CALL statement is executed, the program specified by the CALL statement can be made available for execution, control is transferred to the called program.After control is returned from the called program, the ON OVERFLOW or ON EXCEPTION phrase, if specified, is ignored and control is transferred to the end of the CALL statement or, if the NOT ON EXCEPTION phrase is specified, to imperative-statement- 2 . In the latter case, execution continues through imperative-statement-2 according to the rules for each statement specified in that statement.If a procedure branching or conditional statement that causes explicit transfer of control is executed, control is transferred in accordance with the rules for that statement; otherwise, upon completion of the execution of imperative-statement-2 , control is transferred to the end of the CALL statement.

If, when a CALL statement is executed, it is determined that the program specified by the CALL statement cannot be made available for execution, the NOT ON EXCEPTION phrase, if specified, is ignored and one of the following two actions occurs:

  1. If either the ON OVERFLOW or the ON EXCEPTION phrase is specified, control is transferred to imperative-statement-1. Execution then continues according to the rules for each statement in imperative-statement-1. If a procedure branching or conditional statement that causes explicit transfer of control is encountered, control is transferred in accordance with the rules for that statement; otherwise, upon completion of the execution of imperative-statement-1, control is transferred to the end of the CALL statement.
  2. If neither the ON OVERFLOW nor the ON EXCEPTION phrase is specified, a runtime error message is produced and execution of the run unit is terminated. Reasons for not making a called program available for execution include the following:
  • It cannot be found using the search patterns, which are described in the RM/COBOL User’s Guide.
  • Its format is not one of the legal formats for an RM/COBOL called program.
  • There is insufficient available memory to load it.

CALL Statement Examples



Face Book Twitter Google Plus Instagram Youtube Linkedin Myspace Pinterest Soundcloud Wikipedia

All rights reserved © 2018 Wisdom IT Services India Pvt. Ltd DMCA.com Protection Status

COBOL Topics