MainframeMaster
MainframeMaster

COBOL Tutorial

Progress0 of 0 lessons

COBOL External Interfaces

External interfaces in COBOL enable communication with systems, services, and programs outside the COBOL application. This includes calling external programs, interfacing with databases, communicating with web services, using system services, and integrating with other programming languages. Understanding external interfaces is essential for building integrated applications, accessing modern services, and extending COBOL capabilities in mainframe and distributed environments.

What are External Interfaces?

External interfaces allow COBOL programs to interact with:

  • External programs: Calling other COBOL programs or programs written in other languages
  • Databases: Accessing relational databases using SQL
  • Web services: Communicating with REST APIs, SOAP services, and HTTP endpoints
  • System services: Using operating system functions and services
  • Other languages: Interfacing with C, Java, and other programming languages
  • File systems: Accessing files and directories through system calls
  • Network services: TCP/IP sockets and network communication

These interfaces extend COBOL's capabilities and enable integration with modern systems and services.

Calling External Programs

The CALL statement invokes external programs or subprograms:

Basic CALL Syntax

cobol
1
2
3
4
5
       CALL "program-name"
           [USING parameter-1 [parameter-2 ...]]
           [ON EXCEPTION imperative-statement]
           [NOT ON EXCEPTION imperative-statement]
       END-CALL.

Components:

  • "program-name": The name of the external program to call (literal or identifier)
  • USING: Optional list of parameters to pass to the called program
  • ON EXCEPTION: Executes if the program cannot be found or executed
  • NOT ON EXCEPTION: Executes if the call succeeds

Example: Calling an External Program

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
       WORKING-STORAGE SECTION.
       01  CUSTOMER-AMOUNT    PIC 9(8)V99 VALUE 1000.00.
       01  TAX-RATE          PIC V999 VALUE 0.08.
       01  TAX-AMOUNT        PIC 9(8)V99.
       01  CALL-STATUS       PIC X VALUE 'N'.
           88  CALL-SUCCESS   VALUE 'Y'.
           88  CALL-FAILED    VALUE 'N'.
       
       PROCEDURE DIVISION.
       MAIN-PARA.
           CALL "CALCULATE-TAX"
               USING CUSTOMER-AMOUNT
                     TAX-RATE
                     TAX-AMOUNT
               ON EXCEPTION
                   DISPLAY "ERROR: Tax calculation program not found"
                   MOVE 'N' TO CALL-STATUS
               NOT ON EXCEPTION
                   DISPLAY "Tax calculated: " TAX-AMOUNT
                   MOVE 'Y' TO CALL-STATUS
           END-CALL
           
           IF CALL-SUCCESS
               DISPLAY "Total amount: " 
                       CUSTOMER-AMOUNT + TAX-AMOUNT
           END-IF
           
           STOP RUN.

Parameter Passing: BY REFERENCE vs BY VALUE

Parameters can be passed by reference (default) or by value:

cobol
1
2
3
4
5
6
7
8
9
10
11
       *> BY REFERENCE (default) - called program can modify
       CALL "PROCESS-DATA"
           USING BY REFERENCE INPUT-DATA
                 BY REFERENCE OUTPUT-DATA
       END-CALL
       
       *> BY VALUE - passes a copy, original cannot be modified
       CALL "VALIDATE-INPUT"
           USING BY VALUE CUSTOMER-ID
                 BY VALUE AMOUNT
       END-CALL

BY REFERENCE passes the memory address, allowing the called program to modify the original variable. BY VALUE passes a copy, protecting the original from modification.

Dynamic Program Calls

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
       WORKING-STORAGE SECTION.
       01  PROGRAM-NAME      PIC X(30) VALUE 'TAX-CALCULATOR'.
       01  PROGRAM-PARAM     PIC X(20).
       
       PROCEDURE DIVISION.
       MAIN-PARA.
           *> Call program using variable name
           CALL PROGRAM-NAME
               USING PROGRAM-PARAM
               ON EXCEPTION
                   DISPLAY "Program " PROGRAM-NAME " not found"
           END-CALL
           
           STOP RUN.

You can use a variable for the program name, allowing dynamic program selection at runtime.

Database Interfaces

COBOL can interface with databases using embedded SQL:

Embedded SQL Syntax

cobol
1
2
3
       EXEC SQL
           sql-statement
       END-EXEC.

SQL statements are embedded in COBOL code and preprocessed before compilation.

Example: Database SELECT

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
       WORKING-STORAGE SECTION.
       01  WS-CUSTOMER-ID     PIC 9(5).
       01  WS-CUSTOMER-NAME   PIC X(30).
       01  WS-CUSTOMER-BALANCE PIC 9(8)V99.
       
       EXEC SQL BEGIN DECLARE SECTION END-EXEC.
       01  SQL-CUSTOMER-ID    PIC 9(5).
       01  SQL-CUSTOMER-NAME  PIC X(30).
       01  SQL-BALANCE        PIC 9(8)V99.
       EXEC SQL END DECLARE SECTION END-EXEC.
       
       PROCEDURE DIVISION.
       MAIN-PARA.
           MOVE 12345 TO SQL-CUSTOMER-ID
           
           EXEC SQL
               SELECT CUSTOMER_NAME, BALANCE
               INTO :SQL-CUSTOMER-NAME, :SQL-BALANCE
               FROM CUSTOMERS
               WHERE CUSTOMER_ID = :SQL-CUSTOMER-ID
           END-EXEC
           
           IF SQLCODE = 0
               MOVE SQL-CUSTOMER-NAME TO WS-CUSTOMER-NAME
               MOVE SQL-BALANCE TO WS-CUSTOMER-BALANCE
               DISPLAY "Customer: " WS-CUSTOMER-NAME
               DISPLAY "Balance: " WS-CUSTOMER-BALANCE
           ELSE
               DISPLAY "SQL Error: " SQLCODE
           END-IF
           
           STOP RUN.

Key points:

  • EXEC SQL BEGIN/END DECLARE SECTION: Declares host variables for SQL
  • Colon prefix (:): Indicates host variables in SQL statements
  • SQLCODE: Check after each SQL statement (0 = success, negative = error)
  • INTO clause: Specifies where to store query results

Example: Database INSERT

cobol
1
2
3
4
5
6
7
8
9
10
11
12
       EXEC SQL
           INSERT INTO CUSTOMERS 
               (CUSTOMER_ID, CUSTOMER_NAME, BALANCE)
           VALUES 
               (:SQL-CUSTOMER-ID, :SQL-CUSTOMER-NAME, :SQL-BALANCE)
       END-EXEC
       
       IF SQLCODE = 0
           DISPLAY "Customer inserted successfully"
       ELSE
           DISPLAY "Insert failed: " SQLCODE
       END-IF

Example: Database UPDATE

cobol
1
2
3
4
5
6
7
8
9
10
11
       EXEC SQL
           UPDATE CUSTOMERS
           SET BALANCE = :SQL-BALANCE
           WHERE CUSTOMER_ID = :SQL-CUSTOMER-ID
       END-EXEC
       
       IF SQLCODE = 0
           DISPLAY "Update successful"
       ELSE
           DISPLAY "Update failed: " SQLCODE
       END-IF

Web Service Interfaces

COBOL can interface with web services, though implementation varies by environment:

Mainframe: CICS Web Services

On mainframes, CICS provides web service support:

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
       *> CICS web service invocation (conceptual)
       EXEC CICS WEB OPEN
           HOST('api.example.com')
           PORTNUMBER(443)
       END-EXEC
       
       EXEC CICS WEB SEND
           GET
           PATH('/api/customers/12345')
       END-EXEC
       
       EXEC CICS WEB RECEIVE
           INTO(WS-RESPONSE-BUFFER)
           LENGTH(WS-RESPONSE-LENGTH)
       END-EXEC

CICS web services allow COBOL programs to act as both web service clients and servers.

HTTP Client Calls

Some COBOL implementations support HTTP directly:

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
       *> HTTP GET request (conceptual, implementation varies)
       CALL "HTTP-GET"
           USING BY REFERENCE WS-URL
                 BY REFERENCE WS-RESPONSE
                 BY REFERENCE WS-STATUS-CODE
       END-CALL
       
       IF WS-STATUS-CODE = 200
           *> Process successful response
           DISPLAY "Response: " WS-RESPONSE
       ELSE
           DISPLAY "HTTP Error: " WS-STATUS-CODE
       END-IF

System Service Interfaces

COBOL can call system services and operating system functions:

System Calls

cobol
1
2
3
4
5
6
7
8
9
10
11
       *> Call system command (conceptual)
       CALL "SYSTEM"
           USING BY REFERENCE WS-COMMAND
                 BY REFERENCE WS-RETURN-CODE
       END-CALL
       
       IF WS-RETURN-CODE = 0
           DISPLAY "Command executed successfully"
       ELSE
           DISPLAY "Command failed: " WS-RETURN-CODE
       END-IF

Date and Time Services

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
       WORKING-STORAGE SECTION.
       01  CURRENT-DATE       PIC 9(8).
       01  CURRENT-TIME       PIC 9(8).
       
       PROCEDURE DIVISION.
       MAIN-PARA.
           *> Get system date
           ACCEPT CURRENT-DATE FROM DATE YYYYMMDD
           
           *> Get system time
           ACCEPT CURRENT-TIME FROM TIME
           
           DISPLAY "Current Date: " CURRENT-DATE
           DISPLAY "Current Time: " CURRENT-TIME
           
           STOP RUN.

Error Handling in External Interfaces

Proper error handling is crucial for external interfaces:

CALL Statement Error Handling

cobol
1
2
3
4
5
6
7
8
9
       CALL "EXTERNAL-PROGRAM"
           USING PARAM-1 PARAM-2
           ON EXCEPTION
               DISPLAY "ERROR: Program not found or failed"
               MOVE 8 TO RETURN-CODE
               STOP RUN
           NOT ON EXCEPTION
               DISPLAY "Call successful"
       END-CALL

SQL Error Handling

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
       EXEC SQL
           SELECT CUSTOMER_NAME
           INTO :SQL-CUSTOMER-NAME
           FROM CUSTOMERS
           WHERE CUSTOMER_ID = :SQL-CUSTOMER-ID
       END-EXEC
       
       EVALUATE SQLCODE
           WHEN 0
               DISPLAY "Query successful"
           WHEN 100
               DISPLAY "No rows found"
           WHEN NEGATIVE
               DISPLAY "SQL Error: " SQLCODE
               DISPLAY "Error message: " SQLERRM
           WHEN OTHER
               DISPLAY "Unexpected SQLCODE: " SQLCODE
       END-EVALUATE

File Status Error Handling

cobol
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
       FD  INPUT-FILE
           FILE STATUS IS WS-FILE-STATUS.
       
       PROCEDURE DIVISION.
       MAIN-PARA.
           OPEN INPUT INPUT-FILE
           
           IF WS-FILE-STATUS NOT = '00'
               DISPLAY "File open error: " WS-FILE-STATUS
               EVALUATE WS-FILE-STATUS
                   WHEN '10'
                       DISPLAY "File not found"
                   WHEN '30'
                       DISPLAY "Permanent I/O error"
                   WHEN OTHER
                       DISPLAY "Unknown error"
               END-EVALUATE
               STOP RUN
           END-IF

Best Practices for External Interfaces

Follow these best practices:

  • Always handle errors: Use ON EXCEPTION for CALL statements, check SQLCODE for SQL, and validate return codes
  • Validate parameters: Ensure parameters passed to external programs are valid and properly formatted
  • Document interfaces: Document expected parameters, return values, and error conditions
  • Use meaningful names: Name external programs and parameters descriptively
  • Test error conditions: Test what happens when external programs fail, databases are unavailable, etc.
  • Handle timeouts: Consider timeout handling for network-based interfaces
  • Validate return codes: Always check return codes, status codes, and error indicators
  • Use appropriate parameter passing: Use BY VALUE for input-only parameters, BY REFERENCE when modification is needed
  • Secure sensitive data: Protect sensitive information when passing to external interfaces
  • Log interface calls: Log external interface calls for debugging and auditing

Common External Interface Patterns

Pattern 1: Service Layer

cobol
1
2
3
4
5
6
7
8
9
10
11
12
       *> Call service layer program
       CALL "CUSTOMER-SERVICE"
           USING BY REFERENCE WS-CUSTOMER-ID
                 BY REFERENCE WS-CUSTOMER-DATA
                 BY REFERENCE WS-SERVICE-STATUS
       END-CALL
       
       IF WS-SERVICE-STATUS = 'SUCCESS'
           *> Process customer data
       ELSE
           *> Handle service error
       END-IF

Pattern 2: Database Access Layer

cobol
1
2
3
4
5
6
7
       *> Encapsulate database access
       CALL "DB-ACCESS"
           USING BY REFERENCE WS-QUERY-TYPE
                 BY REFERENCE WS-QUERY-PARAMS
                 BY REFERENCE WS-QUERY-RESULT
                 BY REFERENCE WS-DB-STATUS
       END-CALL

Pattern 3: Validation Service

cobol
1
2
3
4
5
       *> Call validation with BY VALUE for safety
       CALL "VALIDATE-DATA"
           USING BY VALUE WS-INPUT-DATA
                 BY REFERENCE WS-VALIDATION-RESULT
       END-CALL

Explain Like I'm 5: External Interfaces

Think of external interfaces like making phone calls:

  • CALL statement is like dialing a phone number - you're calling another program to help you
  • Parameters are like the information you tell the person on the phone - you're sharing data
  • ON EXCEPTION is like what happens when the phone is busy or no one answers - you handle the problem
  • Database interfaces are like calling a library to look up information - you ask questions and get answers
  • Web services are like calling a service hotline - you can get help from services on the internet

So external interfaces are ways for your COBOL program to "call" other programs, databases, or services to get help or information - just like making phone calls!

Practice Exercises

Complete these exercises to reinforce your understanding:

Exercise 1: Basic CALL

Create a main program that calls an external program to calculate the square of a number. Pass the number and receive the result. Handle the case where the program is not found.

Exercise 2: Parameter Passing

Create a program that demonstrates BY REFERENCE and BY VALUE. Call an external program that modifies parameters, and observe the difference in behavior.

Exercise 3: SQL Interface

Write a COBOL program that uses embedded SQL to query a customer table. Retrieve customer information based on customer ID and display the results. Handle SQL errors appropriately.

Exercise 4: Error Handling

Create a program that calls multiple external programs and handles errors for each. Use different error handling strategies and provide meaningful error messages.

Exercise 5: Service Integration

Design a program that calls an external validation service, then calls a database service to store validated data. Handle errors at each step and provide appropriate feedback.

Test Your Knowledge

1. What is the primary statement for calling external programs in COBOL?

  • INVOKE
  • CALL
  • EXECUTE
  • RUN

2. How are parameters passed by default in CALL statements?

  • By value
  • By reference
  • By copy
  • By pointer

3. What do you use to interface with databases in COBOL?

  • FILE operations
  • Embedded SQL (EXEC SQL)
  • CALL statements
  • MOVE statements

4. What handles errors when a CALLed program cannot be found?

  • ON ERROR clause
  • ON EXCEPTION clause
  • ERROR HANDLER
  • TRY-CATCH

5. What is the main difference between CALL BY REFERENCE and CALL BY VALUE?

  • BY REFERENCE is faster
  • BY REFERENCE allows modification of original data, BY VALUE passes a copy
  • BY VALUE is the default
  • There is no difference

6. How do you check for SQL errors after an EXEC SQL statement?

  • Check SQLERRM
  • Check SQLCODE (0 = success, negative = error)
  • Check SQLSTATE
  • Check RETURN-CODE

Related Concepts

Related Concepts

CALL Statement

Learn about calling external programs

SQL in COBOL

Understanding database integration

Program Linkage

Learn about parameter passing

System Services

Understanding system calls and services

Related Pages