MainframeMaster

COBOL Tutorial

Progress0 of 0 lessons

ENTRY-CONVENTION

Overview

The ENTRY-CONVENTION clause is used to specify calling conventions for methods in object-oriented COBOL. This clause defines how methods are called and how parameters are passed, ensuring compatibility with different programming languages and platforms.

This clause is particularly important when interfacing with external libraries, system calls, or when working in mixed-language environments where different calling conventions may be required.

Syntax

ENTRY-CONVENTION IS {CONVENTION-NAME}

Where CONVENTION-NAME can be:

  • STDCALL - Standard calling convention
  • CDECL - C declaration calling convention
  • PASCAL - Pascal calling convention
  • FORTRAN - FORTRAN calling convention
  • COBOL - Native COBOL calling convention

Common Use Cases

1. External Library Integration

When calling functions from external libraries written in C or other languages.

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
       IDENTIFICATION DIVISION.
       PROGRAM-ID. ExternalCallExample.
       
       ENVIRONMENT DIVISION.
       CONFIGURATION SECTION.
       SPECIAL-NAMES.
           ENTRY-CONVENTION IS CDECL.
       
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  ExternalFunction    PROCEDURE-POINTER.
       
       PROCEDURE DIVISION.
           SET ExternalFunction TO ENTRY "external_lib_function"
           CALL ExternalFunction
               USING BY VALUE 123
               RETURNING Result
           END-CALL

2. System API Calls

For calling operating system APIs that require specific calling conventions.

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
       IDENTIFICATION DIVISION.
       PROGRAM-ID. SystemAPICall.
       
       ENVIRONMENT DIVISION.
       CONFIGURATION SECTION.
       SPECIAL-NAMES.
           ENTRY-CONVENTION IS STDCALL.
       
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  SystemAPI    PROCEDURE-POINTER.
       
       PROCEDURE DIVISION.
           SET SystemAPI TO ENTRY "GetSystemTime"
           CALL SystemAPI
               USING SystemTimeStruct
           END-CALL

3. Mixed Language Development

When working in environments with multiple programming languages.

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
       IDENTIFICATION DIVISION.
       PROGRAM-ID. MixedLanguageExample.
       
       ENVIRONMENT DIVISION.
       CONFIGURATION SECTION.
       SPECIAL-NAMES.
           ENTRY-CONVENTION IS PASCAL.
       
       DATA DIVISION.
       WORKING-STORAGE SECTION.
       01  PascalFunction    PROCEDURE-POINTER.
       
       PROCEDURE DIVISION.
           SET PascalFunction TO ENTRY "pascal_calc"
           CALL PascalFunction
               USING Param1 Param2
               RETURNING Result
           END-CALL

Best Practices and Tips

✅ Do's

  • Always specify ENTRY-CONVENTION when calling external functions
  • Use CDECL for most C library functions
  • Use STDCALL for Windows API calls
  • Document the calling convention requirements
  • Test thoroughly with the target platform

❌ Don'ts

  • Don't assume default calling conventions
  • Don't mix calling conventions without proper testing
  • Don't ignore platform-specific requirements
  • Don't use incompatible calling conventions

Performance Considerations

The choice of calling convention can impact performance:

  • CDECL - Caller cleans up stack, more flexible but slightly slower
  • STDCALL - Callee cleans up stack, more efficient for frequent calls
  • PASCAL - Parameters pushed left-to-right, may be faster on some platforms
  • COBOL - Native convention, typically fastest for COBOL-to-COBOL calls

When to Use

External Library Integration: When calling functions from C, C++, or other language libraries
System API Calls: When interfacing with operating system APIs
Mixed Language Development: In environments with multiple programming languages
Platform-Specific Requirements: When targeting specific platforms with known calling conventions

Quick Reference

ConventionStack CleanupParameter OrderCommon Use
CDECLCallerRight-to-leftC libraries
STDCALLCalleeRight-to-leftWindows API
PASCALCalleeLeft-to-rightPascal libraries
COBOLCalleeLeft-to-rightCOBOL programs

Test Your Knowledge

1. Which calling convention is typically used for C library functions?

  • STDCALL
  • CDECL
  • PASCAL
  • COBOL

2. What is the main difference between CDECL and STDCALL?

  • Parameter order
  • Stack cleanup responsibility
  • Return value handling
  • Memory allocation

3. When should you specify ENTRY-CONVENTION?

  • Always, for all method calls
  • Only when calling external functions
  • Only for COBOL-to-COBOL calls
  • Never, it's automatic

⚠️ Important Notes

  • Calling conventions are platform-specific and may vary between compilers
  • Incorrect calling conventions can cause program crashes or undefined behavior
  • Always refer to the target platform's documentation for specific requirements
  • Test thoroughly when using non-standard calling conventions

Related Concepts

PROCEDURE-POINTER

Understanding procedure pointers for external calls.

CALL Statement

Understanding the CALL statement for external function calls.

EXTERNAL

Understanding external program declarations.

SPECIAL-NAMES

Understanding special names configuration.

ENVIRONMENT DIVISION

Understanding environment division configuration.

DEBUG-CONTENTSEXCEPTION-OBJECT

Frequently Asked Questions