Chapter 7: Library Routines

This chapter describes the COBOL library routines that you can use to control debugging.

7.1 Debugging Routines

The COBOL system library routines use type definitions and COBOL CALL prototypes; this helps you to ensure that all calls to these routines are valid. For further information see the section Using the Library Routine TYPEDEFs and CALL Prototypes in the chapter Library Routines in your Programmer's Guide to Writing Programs.

To ensure that the type definitions and CALL protoypes are used by your program, you should include the copyfile $COBDIR/cpylib/cblproto.cpy in your program. cblproto.cpy must be copied before the Identificaton Division of the program being compiled.

The following debugging routines are available:

CBL_DEBUGBREAK Enables a COBOL program to invoke Animator.
CBL_FFND_REPORT Enables a COBOL program to invoke FaultFinder

7.2 Key to COBOL System Library Routines

Descriptions for all of the library routines appear alphabetically. Each description contains the routine name and function and the following entries (as appropriate).

Shows the CALL statement you can use to call the routine.

The optional RETURNING clause is also shown. Every routine returns a value showing the result of the operation. Unless otherwise indicated, zero indicates success, nonzero indicates failure. This value is left in the data item specified in the RETURNING clause; the data item used in this chapter is status-code. If this clause is omitted, the value is left in the special register RETURN-CODE. (If bit two of the call convention number is set, RETURN-CODE is not changed. See the chapter The COBOL Interfacing Environment in your Programmer's Guide to Writing Programs for details of call conventions.)

status-code must be a numeric data item capable of holding positive values from 0 to 65535; it is defined as in cbltypes.cpy as cblt-rtn-code.

The name of the routine must be coded in upper case.

Describes any parameters shown in the RETURNING and USING clauses. A parameter enclosed in brackets, for example, [parameter1] is optional and might not be needed for all forms of the routine.
On Entry:
Indicates which of the parameters shown are passed on entry.
On Exit:
Indicates which of the parameters shown are returned on exit.
Where bits of one or more bytes are referenced, bit 0 is the least significant (right-most) bit.
Provides any additional information necessary for the successful use of the routine.


Enables a COBOL program to invoke Animator.

call "CBL_DEBUGBREAK" returning status-code
status-code See Key

You can use this call to invoke Animator. If the program is not being debugged when it calls CBL_DEBUGBREAK, it starts Animator and then comes to a halt, as if you had been debugging it already and then pressed the Stop button on the toolbar.

If the program was already being debugged when it called CBL_DEBUGBREAK, then debugging comes to a halt in Animator, as if you had pressed the Stop button.

The routine returns a value 0 if the call was successful, or non-zero if it tried to invoke Animator but failed.


Enables a COBOL program to invoke FaultFinder.

CALL "CBL_FFND_REPORT" using  by value rtserr
                              by value terminate
                              returning status-code
rtserr cblt-x4-comp5.
terminate cblt-x4-comp5.
status-code See Key
On Entry:
terminate Can be one of the following:
0 Continue execution after the FaultFinder report is produced.
1 Terminate the run-time system after the FaultFinder report is produced. If rtserr is non-zero, that run-time system error is reported on exit.
rtserr If non-zero, this is a valid run-time system error code that is reported by FaultFinder. If zero, no run-time system error is reported.

You can use this call to invoke FaultFinder, which immediately generates a report file based on the current settings of the FaultFinder run-time tunables. If the faultfind_level tunable is zero, CBL_FFND_REPORT still runs successfully; however, the FaultFinder report contains no traceback information or open file information. Whether the program continues executing subsequent to FaultFinder producing its report depends on the value you set for terminate.

Copyright © 2000 MERANT International Limited. All rights reserved.
This document and the proprietary marks and names used herein are protected by international law.