About Call Prototypes

Prototypes can help you write multi-program applications that function as you expect. For information on the CALL statement syntax see your Language Reference

When a COBOL program calls another program there is no validation of the type or the number of parameters provided in the CALL statement. If there is a mismatch between the parameter types provided on the CALL statement's USING clause and those of the called program's Linkage Section as referenced in the USING clause of the Procedure Division, then it is likely that either an application error or a run-time system error will occur.

For example, suppose you had the following program Mymain:

program-id. MYMAIN.
 working-storage section.
  01  .
     05 myhandle         pic x(4).
     05 othervalue       pic x(4) value "6x3b".
 procedure division.
     call 'MYROUTINE'   using myhandle
     display "Othervalue is " othervalue.

and the subprogram Myroutine:

program-id. MYROUTINE.
  linkage section.
  01  myhandle            usage pointer.
  procedure division using myhandle.
      set myhandle        to null
      exit program.

The program and its subprogram would work as you expected if compiled and run on a 32-bit system (where pointers are 4 bytes long), but would corrupt the value othervalue on a 64-bit system (where pointers are 8 bytes long).

You could be informed about this kind of problem when you compiled the programs, if the compiler had access to the data types expected by the called program Myroutine when it compiled the program Mymain. Call prototypes provide this information about called programs, and enable the compiler to check for semantic consistency between the parameters in both the calling program, and in the called subprogram.

A call prototype can be regarded as a cut-down version or model of the code of the called program. The prototype contains:

No code is required in the Procedure Division.

A call prototype is identified by the use of the IS EXTERNAL clause in the Program-ID paragraph.

If you were to code the calling program above (Mymain) as follows:

  program-id. MYROUTINE is EXTERNAL.      
  linkage section.                       
  01  myhandle            usage pointer.
  procedure division using myhandle.     
  end program MYROUTINE.
  ******************************************************
  * Prototypes are usually defined in a copyfile, but  *
  * here it is placed in-line                          *
  ******************************************************
  
  program-id. MYMAIN.
  working-storage section.
  01  .
      05 myhandle         pic x(4).
      05 othervalue       pic x(4) value "6x3b".
  procedure division.
      call 'MYROUTINE'   using myhandle
      display "Othervalue is " othervalue.
  end program MYMAIN.

when you compiled the program you would receive this warning message:

    14      call 'MYROUTINE'   using myhandle
*1059-E****************************************
**    Parameter is not consistent with that defined
      in prototype

Coding your programs in this way enables you to recognise programming errors without having to do run-time tests.

Ideally, all programs called from COBOL should be prototyped; however, this is not practical, as there is already a substantial body of COBOL code, and COBOL programmers are not used to type-checking programs. Even if the effort was expended to prototype all calls a program makes, it is likely that strict type-checking would cause a large number of Compiler errors on valid COBOL calls. For this reason, your COBOL system enables you to prototype called programs using a relaxed form of type-checking, and/or the keyword ANY with a USING statement.

For an extended example of using call prototypes, see the topic Call Prototypes in the section Examples in your Language Reference.

The COBOL system library routines are prototyped, enabling you to ensure that data items defined in your programs match those expected by the library routines. This is particularly useful if you are porting 32-bit applications to 64-bit systems, and want to ensure that data items are typed correctly.