CBL_DEBUG_START

Enables a COBOL program to initiate advanced remote debugging or cross-session debugging.

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 and the specified `timeout` has elapsed. 0 Start local 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.

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. 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 debugging comes to a halt in Animator, as if you had pressed the interrupt key.

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