Starting the debugger automatically using library routines

You can cause debugging to be triggered at a specific point in your code by using the CBL_DEBUGBREAK and CBL_DEBUG_START library routines. This is particularly useful for debugging dynamic link libraries that are called by other programs.

These statements are often included through conditional compilation so that they can be enabled or disabled by setting a directive. In the example below, CBL_DEBUGBREAK is called only if the user sets CONSTANT DEBUG(1) as a compiler directive before building the application.

Use CBL_DEBUGBREAK to invoke the debugger.

Alternatively use CBL_DEBUG_START and CBL_DEBUG_STOP to respectively attach and detach the debugger to the application. These routines include parameters that give you more control over debugging, such as identifying which debugger process should start and how long to wait for it to do so.

1. Add calls to the routines at the relevant points in your programs, and rebuild your application. See code examples below.
2. In your project properties, enable the Wait for debuggable attachment Launch option with either the Wait for any program or Wait for ID sub-options depending on which library routine(s) you have called in your programs. See To launch a debug process using Wait for debuggable attachment for details.
3. Set any other debug options you require.
4. Start the debugger.

The debugger remains in a wait state until CBL_DEBUGBREAK or CBL_DEBUG_START is executed. If you use CBL_DEBUG_START you can then use CBL_DEBUG_STOP to detach the debugger from the application, which resumes running without the debugging features.

            perform with test after
               until char not = "Y" and char not = "y"
               call clear-screen
               
               display
                   "To select a square type a number between 1 and 9"
                   upon crt
               perform init
               move "Shall I start ? " to question
               perform get-reply
                  $if DEBUG defined
                     call "CBL_DEBUGBREAK"
                  $end
               if char = "Y" or char = "y"
                     move 10 to check(5)
                   perform put-move
               end-if
               perform new-move
               until game not = spaces
               move "Play again ?    " to question
               perform get-reply
           end-perform.

       working-storage section.
       copy 'cbltypes.cpy'.

       01 dbg. 
           02 flgs             cblt-os-flags.
           02 tmout            cblt-os-ssize.
           02 identifier       pic x(80) value "XsessID ".
           02 st-code          pic x(2) COMP-5.

       01 transaction          pic x(80).

       01 stop-flags           cblt-os-flags.

       01 argument             pic x(80).

       procedure division.
	      move "transaction" to argument

           *> Set CBL_DEBUG_START flags to :-
           *> Start debugging via a waiting debugger,
           *> when a debuggable program is entered.
           *> Error if no debugger is available.
           *>
           move h"03" to flgs
           move 0 to tmout

           *> Set CBL_DEBUG_STOP flags to :-
           *> Stop debugging and return the debugger to
           *> a waiting state
           *>
           move h"01" to stop-flags

           *> Run the transaction
           perform run-transaction

		     call "CBL_THREAD_SLEEP" using by value 5000 size 4
		   
           *> Run the transaction
           perform run-transaction
           stop run.

       run-transaction section.
           call "CBL_DEBUG_START" using by value flgs
                                                 tmout
                                    by reference identifier
                                       returning st-code
           if st-code not = 0
               display "No waiting debugger"
               goback
           end-if

           call argument

           call "CBL_DEBUG_STOP" using by value stop-flags
                                     returning st-code
           if st-code not = 0
               display "Failed to stop debugger"
           end-if
           .