This chapter describes the COBOL library routines that you can use to control debugging.
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|
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
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
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.|
|Indicates which of the parameters shown are passed on entry.|
|Indicates which of the parameters shown are returned
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
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
||Can be one of the following:
||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
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.