COBOL Tutorial

COBOL CALL-CONVENTION Clause - Quick Reference

Progress0 of 0 lessons

Overview

The CALL-CONVENTION clause specifies the calling convention used when invoking external programs or system functions. It defines how parameters are passed and how the program interface works during external calls.

Purpose and Usage

Parameter passing - Define how parameters are passed between programs
Interface compatibility - Ensure proper program linkage
External calls - Specify conventions for external program calls
System integration - Interface with system functions and APIs
Performance optimization - Choose appropriate calling mechanisms

Calling Convention Concept

Calling Program → CALL-CONVENTION → Called Program

Parameters: [param1, param2, param3]

Return: [result]

Convention determines parameter passing mechanism

CALL-CONVENTION defines the protocol for program communication.

Syntax

The CALL-CONVENTION clause follows specific syntax patterns within the SPECIAL-NAMES paragraph and can use various convention values.

Basic Syntax

cobol

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
* Basic CALL-CONVENTION syntax
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
    CALL-CONVENTION IS convention-name.
 
* With specific convention
SPECIAL-NAMES.
    CALL-CONVENTION IS STANDARD.
 
* Multiple conventions
SPECIAL-NAMES.
    CALL-CONVENTION IS STANDARD
    CALL-CONVENTION IS EXTERNAL.
 
* Complete example
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
    CALL-CONVENTION IS STANDARD
    CLASS VALID-STATUS IS "00" THRU "99".

CALL-CONVENTION is specified in the SPECIAL-NAMES paragraph.

Common Convention Values

Convention	Usage	Characteristics
STANDARD	Default COBOL calls	Parameters by reference
EXTERNAL	External program calls	System-specific interface
CUSTOM	User-defined conventions	Flexible parameter passing
FASTCALL	Performance optimization	Optimized for speed
STDCALL	Standard C calls	C-compatible interface

Parameter Passing Mechanisms

cobol

1
2
3
4
5
6
7
8
9
10
11
12
13
* By reference (default for STANDARD)
CALL "SUBPROGRAM" USING PARAM1 PARAM2
 
* By value (some external conventions)
CALL "EXTERNAL-PROG" USING BY VALUE PARAM1
 
* By content (copy value)
CALL "SUBPROGRAM" USING BY CONTENT PARAM1
 
* Mixed passing
CALL "MIXED-PROG" USING BY REFERENCE PARAM1
    BY VALUE PARAM2
    BY CONTENT PARAM3

Different conventions support different parameter passing methods.

Practical Examples

These examples demonstrate how to use the CALL-CONVENTION clause effectively in different program calling scenarios.

Standard COBOL Program Call

cobol

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
IDENTIFICATION DIVISION.
PROGRAM-ID. MAIN-PROGRAM.
 
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
    CALL-CONVENTION IS STANDARD.
 
DATA DIVISION.
WORKING-STORAGE SECTION.
01  WS-PARAM1         PIC X(20) VALUE "Hello World".
01  WS-PARAM2         PIC 9(5) VALUE 12345.
01  WS-RESULT         PIC X(50).
 
PROCEDURE DIVISION.
MAIN-PROCESS.
    * Call subprogram with standard convention
    CALL "SUBPROGRAM" USING WS-PARAM1 WS-PARAM2
        RETURNING WS-RESULT
    
    DISPLAY "Result: " WS-RESULT
    STOP RUN.
 
* Called subprogram
IDENTIFICATION DIVISION.
PROGRAM-ID. SUBPROGRAM.
 
DATA DIVISION.
LINKAGE SECTION.
01  LK-PARAM1         PIC X(20).
01  LK-PARAM2         PIC 9(5).
01  LK-RESULT         PIC X(50).
 
PROCEDURE DIVISION USING LK-PARAM1 LK-PARAM2
    RETURNING LK-RESULT.
    
    * Process parameters
    STRING LK-PARAM1 DELIMITED BY SPACE
           " - Value: " DELIMITED BY SIZE
           LK-PARAM2 DELIMITED BY SIZE
           INTO LK-RESULT
    
    EXIT PROGRAM.

Standard COBOL program call using the default calling convention.

External System Function Call

cobol

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
IDENTIFICATION DIVISION.
PROGRAM-ID. EXTERNAL-CALL-EXAMPLE.
 
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
    CALL-CONVENTION IS EXTERNAL.
 
DATA DIVISION.
WORKING-STORAGE SECTION.
01  WS-SYSTEM-FUNCTION PIC X(20) VALUE "GETSYSTEMTIME".
01  WS-TIME-BUFFER     PIC X(50).
01  WS-RETURN-CODE     PIC 9(4).
 
PROCEDURE DIVISION.
MAIN-PROCESS.
    * Call external system function
    CALL WS-SYSTEM-FUNCTION USING WS-TIME-BUFFER
        RETURNING WS-RETURN-CODE
    
    IF WS-RETURN-CODE = 0
        DISPLAY "System time: " WS-TIME-BUFFER
    ELSE
        DISPLAY "Error getting system time"
    END-IF
    
    STOP RUN.
 
* Example of calling C library function
PROCEDURE DIVISION.
CALL-C-FUNCTION.
    * Call C library function (example)
    CALL "strlen" USING BY VALUE WS-TIME-BUFFER
        RETURNING WS-RETURN-CODE
    
    DISPLAY "String length: " WS-RETURN-CODE.

External system function call using EXTERNAL calling convention.

Custom Calling Convention

cobol

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
IDENTIFICATION DIVISION.
PROGRAM-ID. CUSTOM-CONVENTION-EXAMPLE.
 
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
    CALL-CONVENTION IS CUSTOM.
 
DATA DIVISION.
WORKING-STORAGE SECTION.
01  WS-CUSTOM-PARAM1   PIC X(30).
01  WS-CUSTOM-PARAM2   PIC 9(8).
01  WS-CUSTOM-RESULT   PIC X(100).
01  WS-CALL-STATUS     PIC X(1).
 
PROCEDURE DIVISION.
MAIN-PROCESS.
    MOVE "Custom parameter data" TO WS-CUSTOM-PARAM1
    MOVE 98765432 TO WS-CUSTOM-PARAM2
    
    * Call with custom convention
    CALL "CUSTOM-SUBPROGRAM" USING 
        BY REFERENCE WS-CUSTOM-PARAM1
        BY VALUE WS-CUSTOM-PARAM2
        BY REFERENCE WS-CUSTOM-RESULT
        BY REFERENCE WS-CALL-STATUS
    
    IF WS-CALL-STATUS = "S"
        DISPLAY "Success: " WS-CUSTOM-RESULT
    ELSE
        DISPLAY "Error in custom call"
    END-IF
    
    STOP RUN.
 
* Custom subprogram with specific interface
IDENTIFICATION DIVISION.
PROGRAM-ID. CUSTOM-SUBPROGRAM.
 
DATA DIVISION.
LINKAGE SECTION.
01  LK-PARAM1         PIC X(30).
01  LK-PARAM2         PIC 9(8).
01  LK-RESULT         PIC X(100).
01  LK-STATUS         PIC X(1).
 
PROCEDURE DIVISION USING LK-PARAM1 LK-PARAM2
    LK-RESULT LK-STATUS.
    
    * Custom processing logic
    STRING "Processed: " DELIMITED BY SIZE
           LK-PARAM1 DELIMITED BY SPACE
           " (ID: " DELIMITED BY SIZE
           LK-PARAM2 DELIMITED BY SIZE
           ")" DELIMITED BY SIZE
           INTO LK-RESULT
    
    MOVE "S" TO LK-STATUS
    EXIT PROGRAM.

Custom calling convention with mixed parameter passing methods.

Performance-Optimized Calls

cobol

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
IDENTIFICATION DIVISION.
PROGRAM-ID. FASTCALL-EXAMPLE.
 
ENVIRONMENT DIVISION.
CONFIGURATION SECTION.
SPECIAL-NAMES.
    CALL-CONVENTION IS FASTCALL.
 
DATA DIVISION.
WORKING-STORAGE SECTION.
01  WS-ARRAY-DATA     PIC X(1000).
01  WS-SEARCH-KEY     PIC X(20).
01  WS-FOUND-POSITION PIC 9(4).
01  WS-CALL-COUNT     PIC 9(6) VALUE 0.
 
PROCEDURE DIVISION.
MAIN-PROCESS.
    * Initialize data
    MOVE "Sample data for searching" TO WS-ARRAY-DATA
    MOVE "search" TO WS-SEARCH-KEY
    
    * Perform multiple fast calls
    PERFORM VARYING WS-CALL-COUNT FROM 1 BY 1
        UNTIL WS-CALL-COUNT > 1000
        
        CALL "FAST-SEARCH" USING 
            BY REFERENCE WS-ARRAY-DATA
            BY REFERENCE WS-SEARCH-KEY
            RETURNING WS-FOUND-POSITION
    END-PERFORM
    
    DISPLAY "Fast search completed"
    STOP RUN.
 
* Optimized search subprogram
IDENTIFICATION DIVISION.
PROGRAM-ID. FAST-SEARCH.
 
DATA DIVISION.
LINKAGE SECTION.
01  LK-ARRAY-DATA     PIC X(1000).
01  LK-SEARCH-KEY     PIC X(20).
01  LK-FOUND-POSITION PIC 9(4).
 
PROCEDURE DIVISION USING LK-ARRAY-DATA LK-SEARCH-KEY
    RETURNING LK-FOUND-POSITION.
    
    * Fast search algorithm
    MOVE 1 TO LK-FOUND-POSITION
    EXIT PROGRAM.

Performance-optimized calls using FASTCALL convention for high-frequency operations.

Best Practices and Considerations

Understanding best practices ensures proper program linkage and system integration.

Calling Convention Best Practices

Use appropriate conventions - Match convention to program type
Document interfaces - Clearly specify parameter requirements
Test thoroughly - Verify parameter passing and return values
Handle errors - Check return codes and status indicators
Consider performance - Choose conventions based on call frequency

Common Pitfalls to Avoid

Pitfall	Problem	Solution
Mismatched conventions	Parameter passing errors	Use compatible conventions
Incorrect parameter types	Data corruption	Match parameter definitions
Missing error handling	Program crashes	Check return codes
Performance issues	Slow execution	Choose appropriate conventions
Platform dependencies	Portability issues	Use standard conventions

Platform-Specific Considerations

cobol

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
* Windows calling conventions
SPECIAL-NAMES.
    CALL-CONVENTION IS STDCALL.    * Standard Windows API calls
 
* Unix/Linux calling conventions
SPECIAL-NAMES.
    CALL-CONVENTION IS EXTERNAL.   * System calls and libraries
 
* Mainframe calling conventions
SPECIAL-NAMES.
    CALL-CONVENTION IS STANDARD.   * Traditional COBOL calls
 
* Cross-platform compatibility
SPECIAL-NAMES.
    CALL-CONVENTION IS CUSTOM.     * Platform-independent interface

Different platforms may require different calling conventions.

CALL-CONVENTION Clause Quick Reference

Convention	Syntax	Usage
STANDARD	CALL-CONVENTION IS STANDARD	Default COBOL program calls
EXTERNAL	CALL-CONVENTION IS EXTERNAL	External program/system calls
CUSTOM	CALL-CONVENTION IS CUSTOM	User-defined conventions
FASTCALL	CALL-CONVENTION IS FASTCALL	Performance optimization
STDCALL	CALL-CONVENTION IS STDCALL	Standard C-compatible calls

Test Your Knowledge

1. What is the primary purpose of the CALL-CONVENTION clause in COBOL?

To define program structure
To specify calling conventions for external programs
To assign file names
To define data types

2. In which division is the CALL-CONVENTION clause typically used?

IDENTIFICATION DIVISION
ENVIRONMENT DIVISION
DATA DIVISION
PROCEDURE DIVISION

3. What does CALL-CONVENTION affect in program calls?

Only program names
Only parameter types
Parameter passing mechanism and calling interface
Only return values

4. Which of the following is a common CALL-CONVENTION value?

STANDARD
CUSTOM
EXTERNAL
All of the above

5. When is CALL-CONVENTION most important?

When calling internal subprograms
When calling external programs or system functions
When defining data structures
When opening files

Frequently Asked Questions

Related Concepts

CALL Statement

Understanding the CALL statement for program invocation.

SPECIAL-NAMES Paragraph

SPECIAL-NAMES paragraph structure and usage.

Program Linkage

Program linkage and modular programming techniques.

Parameter Passing

Parameter passing mechanisms in COBOL.

Environment Division

Environment division structure and components.

ASSIGN TO Clause COMMUNICATION SECTION

COBOL Tutorial

COBOL CALL-CONVENTION Clause - Quick Reference

Overview

Purpose and Usage

Calling Convention Concept

Syntax

Basic Syntax

Common Convention Values

Parameter Passing Mechanisms

Practical Examples

Standard COBOL Program Call

External System Function Call

Custom Calling Convention

Performance-Optimized Calls

Best Practices and Considerations

Calling Convention Best Practices

Common Pitfalls to Avoid

Platform-Specific Considerations

CALL-CONVENTION Clause Quick Reference

Test Your Knowledge

Frequently Asked Questions

What is the difference between different CALL-CONVENTION values?

How does CALL-CONVENTION affect parameter passing?

When should you use CALL-CONVENTION in your COBOL programs?

What are the performance implications of different CALL-CONVENTION values?

How do you handle CALL-CONVENTION compatibility issues?

Related Concepts

CALL Statement

SPECIAL-NAMES Paragraph

Program Linkage

Parameter Passing

Environment Division

Related Pages