CBL_DEBUG

Note: This routine is supported for native COBOL only.

Syntax:

CALL "CBL_DEBUG_START" using  by value      flags
                                            timeout
                              by reference  identifier
                              returning     status-code

Parameters:

	Using call prototype (see Key)	Picture
`flags`	cblt-os-flags	pic x(4) comp-5 or pic x(8) comp-5 (64-bit native programs only)
`timeout`	cblt-os-ssize	pic s9(9) comp-5 or pic s9(18) comp-5 (64-bit native programs only)
`identifier`		pic x(`n`)
`status-code`	See Library Routines - Key

On Entry:

flags

Controls how animation starts. You can set the following bits:

Bit	Meaning
0	Action if no cross-session or remote Animator process waiting for the specified identifier, and the specified `timeout` has elapsed. 0 Attempt to match with a cross-session or remote Animator process waiting to attach to any process; if no such process is waiting, start local debugging using character Animator (UNIX only) or Just-In-Time debugging. 1 Return an error status.
1	When debugging should start. 0 Start debugging immediately. 1 Start debugging when the next debuggable entry point is entered; this is the first statement in the next animatable COBOL program called, or the first statement in the next piece of animatable COBOL code called using an ENTRY statement.
2	Initiates a live recording.

timeout

Timeout, in milliseconds, to wait for a cross-session or remote Animator process to start. A timeout of 0 means do not wait; a timeout of -1 means wait indefinitely.

identifier

A unique string that identifies which waiting Animator process to attach to, or if live recording is active (flags, bit 2), the string identifies the name of the live recording file to be used. The string must be space- or null-terminated.

Comments:

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 the COBANIMSRV environment variable is set its value is used as the identifier string.
If it is not set, the program attaches to any Animator process started in the same directory.

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.