ILE COBOL – Procedures

In ILE COBOL, the CALL statement transfers control to another program or procedure, which is defined in the ‘PROCEDURE DIVISION USING’ phrase of the called program to receive parameters. The called program returns control to the calling program using an EXIT PROGRAM or GOBACK statement.

Syntax

There are mainly two syntax formats of CALL statement categorized via linkage type.

FORMAT1

FORMAT 2

Explanation of terms used in CALL statements:

There are multiple terms used in both formats that are inseparable part of the CALL statements.

• Literal-1 (CALL Literal-1).

  e.g. CALL ‘PGM01’

  Here, `Literal-1` specifies the name of the target OPM or ILE COBOL subprogram. With the *PGM object type, it is mandatory that this object exists within the current library list. If a program object named ‘PGM01’ (with the *PGM object type) is not found in the library list, the program will abort. It will end with the error MCH3401 – Cannot resolve to object PGM01.

  Example:

  PROCESS APOST.                 
   IDENTIFICATION DIVISION.       
  *-----------------------*       
   PROGRAM-ID.       ERRHNDL31A.  
   AUTHOR.           PROGRAMMER.  
   PROCEDURE DIVISION.            
  *-------------------*           
   MAIN-LOGIC.                    
       CALL 'PGM01'               
       STOP RUN.                  
  

  Error:

  Cannot resolve to object PGM01. Type and Subtype X'0201' Authority X'0000'.  
  Function check. MCH3401 unmonitored by ERRHNDL31A at statement 0000000005, instruction X'0000'. 
  

• Identifier (CALL Identifier).
  e.g.

  MOVE ‘PGM02’      TO WS-PGM-NAME

  CALL WS-PGM-NAME

  Here, ‘Identifier’ holds the name of the target OPM or ILE COBOL subprogram. With the *PGM object type, it is mandatory that this object exists within the current library list. If a program object named ‘PGM02’ (with the *PGM object type) is not found in the library list, the program will abort. It will end with the error MCH3401 – Cannot resolve to object PGM02.

  Example:

  PROCESS APOST.    
   IDENTIFICATION DIVISION. 
  *-----------------------* 
   PROGRAM-ID.       ERRHNDL31B.              
   AUTHOR.           PROGRAMMER.   
   DATA DIVISION.                 
  *--------------*     
   WORKING-STORAGE SECTION. 
   01  WS-PGM-NAME    PIC X(10) VALUE 'PGM02'.
   PROCEDURE DIVISION.       
  *-------------------*  
   MAIN-LOGIC. 
       CALL WS-PGM-NAME.   
       STOP RUN.  
  

  Error:

  Cannot resolve to object PGM02. Type and Subtype X'0201' Authority X'0000'. 
  Function check. MCH3401 unmonitored by ERRHNDL31B at statement 0000000007, instruction X'0000'. 
  

• EXCEPTION or OVERFLOW Phrase.

  e.g. CALL ‘PGM01’

       ON EXCEPTION DISPLAY ‘CANNOT RESOLVE TO OBJECT PGM01’.

  e.g. CALL ‘PGM02’

       ON OVERFLOW DISPLAY ‘CANNOT RESOLVE TO OBJECT PGM02’.

  EXCEPTION or OVERFLOW phrase is used to trap & handle the error – specifically MCH3401 (Cannot resolve to object).

  Example:

  PROCESS APOST.               
   IDENTIFICATION DIVISION.     
  *-----------------------*     
   PROGRAM-ID.       ERRHNDL31B.
   AUTHOR.           PROGRAMMER.
   DATA DIVISION.   
  *--------------*              
   WORKING-STORAGE SECTION.     
   01  WS-PGM-NAME    PIC X(10) VALUE 'PGM02'.       
   PROCEDURE DIVISION.          
  *-------------------*         
   MAIN-LOGIC.
       CALL 'PGM01' ON OVERFLOW 
            DISPLAY 'CANNOT RESOLVE TO OBJECT PGM01'.
       CALL WS-PGM-NAME ON EXCEPTION                 
            DISPLAY 'CANNOT RESOLVE TO OBJECT PGM02'.
       STOP RUN.                
  

  Output:

  CANNOT RESOLVE TO OBJECT PGM01 
  CANNOT RESOLVE TO OBJECT PGM02  
  

• LINKAGE TYPE Phrase.

  In ILE COBOL, there are two primary linkage types when using the CALL literal statement to call an external program, internal procedure or external procedure:

  • PROGRAM (*PGM) (dynamic program calls)
  • PROCEDURE (*MODULE). (statis procedure calls)

  Examples: For dynamic program calls

  CALL ‘PROG01’.
  CALL PROGRAM ‘PROG01’.
  CALL LINKAGE PROGRAM ‘PROG01’.
  CALL LINKAGE TYPE IS PROGRAM ‘PROG01’.

  PROG01(*PGM):

   IDENTIFICATION DIVISION.
  *-----------------------*
   PROGRAM-ID.       PROG01.  
   AUTHOR.           PROGRAMMER.                
   DATA DIVISION.          
  *---------------------*  
   WORKING-STORAGE SECTION.
   01  WS-DATE           PIC 9(08).             
   PROCEDURE DIVISION.     
  *-------------------*    
   MAIN-LOGIC.             
       ACCEPT WS-DATE       FROM DATE YYYYMMDD. 
       DISPLAY 'WS-DATE:'        WS-DATE.       
       STOP RUN.           
  

  CALL02(*PGM):

  PROCESS APOST.     
   IDENTIFICATION DIVISION. 
  *-----------------------* 
   PROGRAM-ID.       CALL02.
   AUTHOR.           PROGRAMMER.           
   PROCEDURE DIVISION.      
  *-------------------*     
   MAIN-LOGIC.              
       CALL PROGRAM 'PROG01'
       ON EXCEPTION         
          DISPLAY 'ERROR IN CALL - PROG01'.
       STOP RUN.            
  

  Examples: For status procedure calls.

  CALL ‘MODULE01’.
  CALL PROCEDURE ‘MODULE01’.
  CALL LINKAGE PROCEDURE ‘MODULE01’.
  CALL LINKAGE TYPE IS PROCEDURE ‘MODULE01’.
  (This part is explained in static procedure call section).

• ‘IN LIBRARY’ Phrase.

  ‘IN LIBRARY’ Phrase is used within a CALL statement to perform a dynamic program call to a specific library on the IBM i system. This phrase does not work with static procedure call.

  e.g.

  CALL ‘PROG01’ IN LIBRARY ‘TESTLAB’.

  e.g.

  01 PGM-NAME       PIC X(10) VALUE ‘PROG1’.

  01 LIB-NAME       PIC X(10) VALUE ‘TESTLAB’

  CALL PGM-NAME IN LIBRARY LIB-NAM.

• ‘END-CALL’ Phrase

  The END-CALL phrase in ILE COBOL is a scope terminator used to explicitly end a CALL statement.

  e.g.

  CALL ‘PROG01’ IN LIBRARY ‘TESTLAB’

  END-CALL.

• ‘USING’ Phrase

  In ILE COBOL, the USING phrase is used in the CALL statement of the calling program and the PROCEDURE DIVISION header of the called program. The data items are matched by their position in the list, data type and data length, not by their names. USING Phrase is typically for passing multiple parameters, data items or data structures.

  Example:

   PROCESS APOST.
   IDENTIFICATION DIVISION.
  *------------------------*
   PROGRAM-ID. MAINPGM.
   AUTHOR.     PROGRAMMER.
   DATA DIVISION.
  *--------------*
   WORKING-STORAGE SECTION.
   01  WS-LAST-CARD-NBR    PIC 9(10) VALUE 4000600001.
   PROCEDURE DIVISION.
  *-------------------*
   MAIN-LOGIC. 
      *> Calling the subprogram using the USING phrase
      CALL ‘SUBPGM’ USING WS-LAST-CARD-NBR
      END-CALL.
      STOP RUN.
  

   PROCESS APOST.
   IDENTIFICATION DIVISION.
  *------------------------*
   PROGRAM-ID. SUBPGM.
   AUTHOR.     PROGRAMMER. 
   DATA DIVISION.
  *--------------*
   LINKAGE SECTION.
   01  LK-CARD-NBR         PIC 9(10).
  
   *> The USING phrase to match the order in the CALL statement
   PROCEDURE DIVISION USING LK-CARD-NBR.
  *------------------*
   MAIN-LOGIC.
      ADD 1 TO LK-CARD-NBR.
      EXIT PROGRAM.
  

• ‘GIVING’ or ‘RETURNING’ Phrase

  In ILE COBOL, the GIVING and RETURNING phrases are used interchangeably to return a single value from a called program back to the caller.

  Example:

   PROCESS APOST.
   IDENTIFICATION DIVISION.
  *------------------------*
   PROGRAM-ID. MAINPGM1.
   AUTHOR.     PROGRAMMER.
   DATA DIVISION.
  *--------------*
   WORKING-STORAGE SECTION.
   01  WS-LAST-CARD-NBR    PIC 9(10) VALUE 4000600001.
   01  WS-NEXT-CARD-NBR    LIKE WS-LAST-CARD-NBR.
   PROCEDURE DIVISION.
  *-------------------*
   MAIN-LOGIC. 
      *> Calling the subprogram using the USING phrase
      CALL ‘SUBPGM1’ USING WS-LAST-CARD-NBR
                     RETURNING WS-NEXT-CARD-NBR  
      END-CALL.
      STOP RUN.
      

   PROCESS APOST.
   IDENTIFICATION DIVISION.
  *------------------------*
   PROGRAM-ID. SUBPGM1.
   AUTHOR.     PROGRAMMER. 
   DATA DIVISION.
  *--------------*
   LINKAGE SECTION.
   01  LK-LAST-CARD-NBR         PIC 9(10).
   01  LK-NEXT-CARD-NBR         LIKE LK-LAST-CARD-NBR.
   *> The USING phrase to match the order in the CALL statement
   PROCEDURE DIVISION USING LK-LAST-CARD-NBR
                      RETURNING LK-NEXT-CARD-NBR.
  *------------------*
   MAIN-LOGIC.
      COMPUTE LK-NEXT-CARD-NBR = LK-LAST-CARD-NBR + 1.
      EXIT PROGRAM.