DEBUG CONNECTION

Start or end debugging of a specific connection or a specific query handle.

Syntax

DEBUG CONNECTION connection_name [STATEMENT statement_name][END]

connection_name ::= identifier

statement_name ::= identifier

Remark

The DEBUG CONNECTION statement makes the connection specified by connection_name into a debuggee of the current debugger session. After the connection becomes a debuggee of the current debugger session, the debugger may debug any SQL scripts executed on the debuggee connection by utilizing the other debug commands such setting the break points, stepping or tracing in the SQL scripts, and view the local variables on the execution stack.

The optional STATEMENT clause indicates that the debugger only wishes to gain debugging control of the specified query handle.

If the current debugger connection is a database connection, it may debug other connections without the optional STATEMENT clause, provided that the user of debugger session is a member of the DB:Admin or DB:Debug groups. If the current debugger connection is a free connection, then the debugger can only debug a specific query handle and the STATEMENT clause is required.

The END clause terminates the debugging process on the specified connection or the specified query. Ending the debug session will allow the SQL script(s) being debugged to continue normal execution.

The connection_name and statement_name are normally obtained via the ::conn.name and ::stmt.name system variables of the debuggee connection. However, if the current debugger connection is a database connection, the connection_name can also be obtained from the ::DEBUG_CONNECTIONS table.

One debugger session can own multiple debuggee but a debuggee can belong to only one debugger session.

Example

// The following example illustrates the basic procedure to debug an

// SQL script.

// 1. Make a debuggee connection. This is the connection on which

// to run the script that will be debugged

// 2. Create a query handle on the debuggee connection and obtain the

// connection name and statement name with the following SQL:

//

// SELECT

// ::conn.name AS connection_name,

// ::stmt.name AS statement_name

// FROM system.iota

//

// Note the connection_name and statement_name from the result set.

// 3. Make a debugger connection. This is the connection where we

// execute debug commands to control the execution of the SQL

// script on the debuggee connection.

//

// 4. Execute the following script on the debugger connection to

// put the debuggee’s query into debug mode and set a break point

// to have the execution of the debuggee SQL script stopping

// before executing the first statement in the script.

// Assuming that the connection_name and statement_name from

// step 2 are 'CONN0001xxxx' and 'STMT0001yyyy' respectively:

 

DEBUG BEGIN;

DEBUG CONNECTION 'CONN0001xxxx' STATEMENT 'STMT0001yyyy';

DEBUG BREAK POINT 'CONN0001xxxx' STATEMENT 'STMT0001yyyy' AT 0 TRANSIENT;

 

// 5. Execute the script to be debugged using the query element

// on the debuggee connection. Suppose the script to be debugged

// is the following:

//

// DECLARE i Integer;

// i = 0;

// WHILE i < 3 DO

// INSERT INTO iTable ( iVal ) VALUES ( i );

// END;

//

// Because of the break point set by the debugger, the execution of the

// script on the debuggee will stop before executing the statement 'i = 0;',

// and it will require further commands from the debugger to continue the

// execution.

// 6. Once the debuggee execution is stopped, the debugger can examine the

// the call stack and local variables of the stopped script. To detect

// stopped the script, the debugger can either poll the ::DEBUG_CONNECTIONS

// table or use the DEBUG WAIT command.

// 7. After done with debugging the script, allows the debuggee to finish

// normally by ending the debugging process on the debuggee:

 

DEBUG CONNECTION 'CONN0001xxxx' END;

See Also

DEBUG BEGIN

DEBUG DATABASE

::DEBUG_CONNECTIONS

::DEBUG_STACK

::DEBUG_BREAKS

::DEBUG_VARIABLES

::DEBUG_SOURCES