CALL "CBL_DEBUG_START" using by value flags timeout by reference identifier returning status-code
|Using call prototype (see Key)
|pic x(4) comp-5
pic x(8) comp-5 (64-bit native programs only)
|pic s9(9) comp-5
pic s9(18) comp-5 (64-bit native programs only)
|See Library Routines - Key
|Action if no cross-session or remote Animator process waiting for the specified identifier, and the specified
timeout has elapsed.
|When debugging should start.
|Initiates a live recording.
Use this call to initiate remote animation or cross-session animation. If the program is not being debugged when it calls CBL_DEBUG_START, the identifier string is used to work out which Animator process to attach to.
If you want to use advanced remote debugging, set the identifier string to the same value as the unique string provided to your COBOL development system command line that initiates remote debugging.
If you want to use cross session debugging, set the identifier string to the same value as the COBANIMSRV environment variable in the other Animator session.
If you leave the identifier string blank, then standard cross-session animation rules are used as follows:
If there is a corresponding Animator process waiting then the program comes to halt and starts being debugged. The program halts immediately if bit 1 of flags is set. If it is not set, execution halts when the next debuggable entry point is reached.
If there is no corresponding Animator process waiting then the program suspends for the number of milliseconds specified in timeout or until an Animator process starts. A timeout of 0 means the call returns immediately, without suspending. A timeout of -1 causes the program to suspend, without timeout, until the Animator process starts.
If there is still no corresponding Animator process to attach to at the end of the timeout period, then the action depends on the setting of bit 0 of flags. If it is set, then the call returns an error status and execution continues. If it is unset, then a local Animator process is started.
If the program was already being debugged when it called CBL_DEBUG_START, then that debug session, whilst obeying the flags, comes to a halt in Animator - that is, if bit 1 of flags is set to 1, the current session stops when the next debuggable entry point is entered.
The routine returns value 0 if the call was successful, or non-zero if it tried to invoke Animator but failed.
If both the debugging and the live recording flag bits are set when you call CBL_DEBUG_START, live recording takes precedence. If you are already debugging a process that attempts to start live recording, that call will fail; as will a call to start debugging if you are already live recording.