Submit Debug Command (QteSubmitDebugCommand) API

The Submit Debug Command (QteSubmitDebugCommand) API allows a client program to issue debug language statements. Debug language statements permit client programs to enter breakpoints, run one or more statements of the program under investigation (step), and evaluate expressions. Watch conditions may also be entered to cause a breakpoint when the contents at a specified storage location are changed.

Authorities and Locks

None.

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The variable that is to receive the results of the Submit Debug Command API. For more information about the structure of the receiver variable, see Variations in Receiver Variable Structure.

The Submit Debug Command API may have more data to return than can be stored in the receiver variable. The bytes available field, described in Variations in Receiver Variable Structure, specifies how large the receiver variable must be to contain the results for the Debug Language statements submitted. If more data is available than the receiver variable can contain, a larger buffer should be provided and the API should be reissued.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable. If the length is larger than the size of the receiver variable, the results may not be predictable. The minimum length is 8 bytes.

View ID

INPUT; BINARY(4)

An identifier of a view of a module whose operation is managed by the source debugger. The view ID is returned as a result of issuing the Register Debug View API. The view ID is used to find debug data associated with the module.

Input buffer

INPUT; CHAR(*)

The input variable that is passed to the Submit Debug Command API. The information passed in the buffer is debug language statements.

Input buffer length

INPUT; BINARY(4)

The length of the data provided in the input buffer.

Compiler ID

INPUT; CHAR(20)

The compiler ID of the compiler that produced the module being debugged. This information is used by the debug translator during expression evaluation. The compiler ID is returned by the Retrieve Module Views (QteRetrieveModuleViews) API.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error code parameter.

Receiver Variable Format

The following table shows the structure of the receiver variable. For more information about the fields contained in the table, see Field Descriptions.

Receiver Variable Structure

Field Descriptions

Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.

Bytes returned. The number of bytes of data returned.

Entry count. The number of entries in the results array. The value of the field is the number of entries in the results array. Each entry occupies 12 bytes. Depending on the kind of information returned, values in entries vary.

Results array. The results of interpreting debug language statements. This is an array of records having similar structures. Each record in the array occupies 12 bytes. There can be up to three fields in each record. Each field occupies 4 bytes and can be interpreted as an unsigned (nonnegative) integer. The first field in a record is the result type field and is used to select the remaining fields. Entries in the result record array fall into several classes. Variations in Receiver Variable Structure depicts several formats of result records.

Statements are interpreted sequentially and the results of each statement are placed in the order in which statements appear in the input buffer. The evaluate statement can return many values if an array or a structure is evaluated. The entry count field contains the number of entries in the results array, and the structure of each entry is summarized in Variations in Receiver Variable Structure.

String space. A sequence of strings. Each string is an array of characters whose last character is a null character.

Description of the Structure of the Receiver Variable

Variations in Receiver Variable Structure illustrates three possible variations in the structure of the receiver variable. The receiver variable consists of the following structures:

• A header record
  This structure consists of three fields:
  
  • Bytes returned
  • Bytes available
  • Entry count
• A result array
• A string space

Each row of Variations in Receiver Variable Structure occupies 12 bytes. The row containing the headings describes the remainder of the receiver variable. The number of bytes returned is assigned to that field. The value of the bytes returned field is always less than or equal to the size of the receiver variable. The number of bytes available may be greater than the number returned. In that case, the client program should reissue the Submit Debug Command API to obtain all data produced for the input debug language statements. The entry count field in the first row indicates the number of 12-byte records, each beginning with a result type field, that follow.

Records beginning with a result type field have the following basic formats.

• The first entry in the array shows a record containing only one field, result type. Records having this structure acknowledge that a kind of debug language statement was translated. An example of this kind of record is the result record for a CLEAR PGM statement.
  
  
• The second entry in the array shows a record containing a count field as well as a result type field. The count field can serve two purposes:
  
  
  • It can acknowledge that a debug language statement was properly translated as in the case of the StepR result record.
    
    
  • It can enumerate the number of related records to follow as in the case of the BreakR result record.
    
    
• The offset field contains the displacement from the start of the receiver variable to the first byte of the character string. All character strings are stored at the end of the receiver variable directly after the record entries. Displacements are measured in bytes.

  The length field contains the number of characters in the character string.

  The last character of each string in the string space has an ordinal value of zero. All characters in the string space occupy 8 bits. The length of a string in the string space does not include the last character.

  Note: The length field will always be set to 512, with each of the 512 characters occupying 16 bits, for a string of type kStringF_E when debugging a JAVA executable. This will occur even when the returned string has a length of less than 512. The end of the returned string can be found by locating the first unicode character in the string that has an ordinal value of zero. As unicode, this character will occupy 16 bits.

• The last row of Variations in Receiver Variable Structure depicts an arbitrarily large string space containing character data. Names and other text fields that are referred to in the result type fields shown in the other rows of Variations in Receiver Variable Structure are stored in this area.

Results Array Entry Structure Summary

The following tables describe each result record in detail. Each result record contains up to three fields and always occupies 12 bytes. The first field, the result type field, is used as an enumerated type. The result type field determines the format of each result record.

Each of the following enumeration constants has both a symbolic name and an ordinal value. The terms symbolic and ordinal refer to enumerations found in programming languages. The symbolic value of an enumeration constant is the symbol, usually a descriptive word that serves as a keyword for the programmer (for example, StepR). The ordinal value of an enumeration constant is the integer constant assigned, usually by the compiler, to the symbolic value. For example, 1 is assigned for StepR.

StepR (1)

Record format StepR is returned as a result of evaluating a step statement.

BreakR (2)

Record format BreakR contains the number of records returned for a break statement.

ClearBreakpointR (3)

Record format ClearBreakpointR contains the line number of the breakpoint removed as a result of interpreting the CLEAR break-position statement.

ClearPgmR (4)

Record format ClearPgmR indicates that all breakpoints have been removed in the current program as result of interpreting the CLEAR PGM statement.

BreakPositionR (5)

Record format BreakPositionR identifies the line number on which a breakpoint was entered. This may not be the same line number as the one entered in the break statement.

EvaluationR (6)

Record format EvaluationR contains the number of records returned for an evaluate statement that are referred to in the subsequent ExpressionValueR record.

ExpressionTextR (7)

Record format ExpressionTextR describes a character string that contains the expression that was evaluated by the evaluate statement.

ExpressionValueR (8)

Record format ExpressionValueR refers to text that contains the formatted value of the expression that is described by the ExpressionTextR record.

ExpressionTypeR (9)

Record format ExpressionTypeR contains the type of the expression whose value is referred to in the ExpressionValueR record.

QualifyR (10)

Record format QualifyR is returned as a result of evaluating a qualify statement.

TypeR (11)

Record format TypeR contains the number of records that are returned for an ATTR statement.

TypeDescR (12)

Record format TypeDescR contains the type and length of the program variable.

DecimalR (13)

Record format DecimalR is returned only for decimal type variables and contains the total and fractional number of digits in the decimal number.

ArrayR (14)

Record format ArrayR is returned only for array type variables and contains the number of dimensions in the array. The ArrayR record is followed by a DimensionR record for each dimension.

DimensionR (15)

Record format DimensionR is returned only for array type variables and contains the low and high bounds of the array dimensions. There is one DimensionR record for each dimension in the array.

WatchR (16)

Record format WatchR contains the number of records returned for a watch statement.

WatchNumberR (17)

Record format WatchNumberR describes the watch condition that was set as a result of the watch statement.

ClearWatchNumberR (18)

Record format ClearWatchNumberR contains the watch number that is cleared as a result of interpreting the CLEAR WATCH watch-number statement.

ClearWatchR (19)

Record format ClearWatchR indicates that all watches in this debug session have been removed as a result of interpreting the CLEAR WATCH ALL statement.

TBreakR (20)

Record format TBreakR contains the number of records that are returned for a tbreak statement.

SBreakR (21)

Record format SBreakR contains the number of records that are returned for a sbreak statement.

TypeDescExtR (22)

Record format TypeDescExtR contains the length of any prefix of the program varying length string variable.

Field Descriptions

Break results count. The number of entries returned for the break statement.

CCSID. The CCSID of the data content. Value 0 indicates the data is of job CCSID.

Dimensions. The number of dimensions in the array.

Expression text length. The number of characters in the expression text.

Expression text offset. The displacement from the start of the receiver variable to the first character of the expression text. Displacement is measured in bytes.

Expression value length. The number of characters in the expression value text.

Expression value offset. The displacement from the start of the receiver variable to the first byte of the expression value text. Displacement is measured in bytes.

Evaluation count. The number of records returned for an evaluate statement.

Expression type. The data type of the expression. The expression type may be one of the following:

Fraction digits. The number of digits to the right of the decimal point in a decimal number.

High bound. The high boundary of the array dimension.

Length. The program variable length that is returned by the TypeDescR result record. The length units are bits.

Length of any prefix. The number of bytes for prefix for any program varying length variable.

Line number. The number of the line on which the action requested was performed.

Low bound. The low boundary of the array dimension.

Reserved. An ignored field.

Result type. The ordinal value of the result array.

SBreak results count. The number of entries returned for the sbreak statement.

Step count. The number of statements processed.

TBreak results count. The number of entries returned for the tbreak statement.

Total digits. The total number of digits in a decimal number.

Type. The program variable type that is returned by the TypeDescR result record. The meanings of this field's value are the same as the expression type field.

Type record count. The number of records returned for an attr statement.

Watch length. The length in bytes of the storage being watched for this watch condition.

Watch number. The identification number assigned to the watch condition. This number is used by various debug functions to identify individual watches.

Watch results count. The number of result records returned for the watch statement.

Statement Results

ATTR Statement Results. The Submit Debug Command API returns a description of the symbol table entry for the program variable entered. A variable number of result records may be produced:

• A TypeR record is returned, which provides a count of the number of records returned for an ATTR statement.
  
  
• A TypeDescR record is returned, which provides the type and size of the program variable.
  
  
• A DecimalR record is returned only if the program variable is a decimal type. This record describes the total and fractional digits in the decimal number.
  
  
• An ArrayR record is returned only if the program variable is an array. This record returns the number of dimensions in an array.
  
  
• A DimensionR record is returned only if the program variable is an array. This record returns the low and high bounds of the array dimensions.

• A TypeDescExtR record is returned only if the program variable is a varying length string. This record returns the number of bytes for prefix for the program varying length variable.

Break Statement Results. The Submit Debug Command API returns a detailed description of the break-position and conditional expression of a conditional breakpoint when a break statement is translated.

The items returned follow:

• The number of records returned as a result of evaluating a break statement. Record type BreakR contains this information.
  
  
• The position on which the breakpoint was entered. Record type BreakPositionR contains the line number of the line on which the breakpoint was entered. Be aware that the input line number may be mapped to a different line. For example, a breakpoint entered on a line that contains a comment is mapped to the next line that contains an operational statement.
  
  
• The text of the expression that defines a conditional breakpoint. Record type ExpressionTextR refers to the text of the condition.

The break statement is interpreted. Program operation is managed by IBM^® i according to the definition of the break statement.

Clear Statement Results. One record is returned. The record type depends on the operand following the keyword CLEAR. If the operand is a line number, the record type is ClearBreakpointR. If the operand is the keyword PGM, the record type is ClearPgmR. If the operand is WATCH and a watch number is specified, the record type is ClearWatchNumberR. If the operand is WATCH and all watches are cleared, the record type is ClearWatchR.

The ClearBreakpointR record contains the line number input for the break position.

The clear statement is interpreted. One or more breakpoints are removed from the program under investigation.

Evaluate Statement Results. An evaluate statement produces a variable number of Result Records. The first four result records follow:

• An EvaluationR record is returned, which enumerates itself and subsequent records. The EvaluationR result record always contains an evaluation count of four.
  
  
• An Expression text record is returned, which contains the offset and length of the string, which represents the expression text.
  
  
• An Expression value record is returned, which contains the offset and length of the string, which represents the value of the expression.

  Note: The length field will always be set to 512, with each of the 512 characters occupying 16 bits, for a string of type kStringF_E when debugging a JAVA executable. This will occur even when the returned string has a length of less than 512. The end of the returned string can be found by locating the first unicode character in the string that has an ordinal value of zero. As unicode, this character will occupy 16 bits.

• An Expression type record is returned, which contains the type of the expression and the CCSID value of the expression.

A single value is returned for an arithmetic expression or scalar variable. Multiple values are returned when a structure is evaluated. Refer to Examples of Result Records Returned by Submit Debug Command API for examples of the result records returned when a structure or an array is evaluated.

The evaluate statement is interpreted. Data is formatted according to the type of the input expression. Refer to Presentation Formats for a description of presentation formats.

Qualify Statement Results. One record is returned. The value of the result type field is QualifyR. The QualifyR record contains the input line number used to establish the current locality for subsequent evaluate statements.

A reference to the block that defines the current locality is assigned by the qualify statement.

SBreak Statement Results. The Submit Debug Command API returns a detailed description of the break-position when an sbreak statement is translated. The items returned are:

• The number of records returned as a result of evaluating a sbreak statement. Record type SBreakR contains this information.
  
  
• The position on which the breakpoint was entered. Record type BreakPositionR contains the line number of the line on which the breakpoint was entered. Be aware that the input line number may be mapped to a different line. For example, a breakpoint entered on a line that contains a comment is mapped to the next line that contains an operational statement.

The sbreak statement is interpreted. Program operation is managed by IBM i according to the definition of the sbreak statement.

Step Statement Results. One record is returned. The value of the result type field is StepR. The StepR record contains the number of statements to be run when control is given to the program under investigation.

The step statement is interpreted. Program processing is managed by IBM i according to the definition of the step statement.

TBreak Statement Results. The Submit Debug Command API returns a detailed description of the thread break-position and conditional expression of a conditional breakpoint when a tbreak statement is translated. The items returned follow:

• The number of records returned as a result of evaluating a tbreak statement. Record type TBreakR contains this information.
  
  
• The position on which the thread breakpoint was entered. Record type BreakPositionR contains the line number of the line on which the thread breakpoint was entered. Be aware that the input line number may be mapped to a different line. For example, a thread breakpoint entered on a line that contains a comment is mapped to the next line that contains an operational statement.
  
  
• The text of the expression that defines a conditional breakpoint for a thread. Record type ExpressionTextR refers to the text of the condition.

The tbreak statement is interpreted. Program operation is managed by IBM i according to the definition of the tbreak statement.

Watch Statement Results. The watch statement returns the following result records:

• A WatchR record is returned, which provides a count of the number of result records for the watch statement.
  
  
• A WatchNumberR record is returned, which contains the watch number assigned and the length in bytes of the storage being watched.
  
  
• An ExpressionTextR record, which contains the offset and length of a string. This record represents the watch statement expression text.
  
  
• An ExpressionValueR record, which contains the offset and length of a string. This record represents the watch storage location address. This value is always a text representation of a space pointer that contains the value of the pointer to the watched storage location (for example, 'SPP:08006F0054001004').

Examples of Result Records Returned by Submit Debug Command API

This section contains examples of result records returned by the Submit Debug Command API. Each example contains a fragment of a program, a debug language statement that appears in the input buffer, and the results produced in the receiver variable.

The null termination symbol denotes the end of a character string in the examples that follow.

Break Statement Example

C Program Fragment

Assume program operation is suspended in the program shown in Figure 1 just before line 6 runs.

Figure 1. Program for Break Example

Line  C Source

 1    #include  stdio.h
 2    int T[] = {1,2,3,5,7,11,13,17,23,29};
 3    int BinarySearch(int v, int f, int l);
 4    main()
 5    { int result;
 6      result = BinarySearch(17,0,9);
 7      printf("result= "); printf("%d",result); printf(" \n");  
 8    }
 

Input Buffer

 

BREAK 7 WHEN result > 5

Receiver Variable

Scalar Evaluate Statement Example

C Program Fragment

Consider the C program fragment in Figure 2. Variable i defines an integer.

Figure 2. Program for Scalar Evaluate Example

Line  C Source

 1    int i = 29;
 

Input Buffer

EVAL i

Receiver Variable

Scalar Evaluate Statement Example

RPG Program Fragment

Consider the RPG program fragment in Figure 3. The fragment assigns 1 to a zoned(1,0) variable I.

The program is currently stopped at line 2.

Figure 3. RPG Programming Language Example, Evaluate

           CL0N01Factor1++++++OpcodeE+Extended-factor2

 1         C                  EVAL    I=1
 2         C                  MOVE    *ON          *INLR
 

Input Buffer

EVAL I

Receiver Variable

Structure Evaluate Statement Example

C Program Fragment

Consider the C program fragment in Figure 4.

Figure 4. Program for Structure Evaluate Example

Line  C Source

 1    struct {
 2        int i;
 3        float f;
 4        struct {
 5           char c;
 6           enum e {red,yellow};
 7        } s2;
 8    } s1 = { 1 , 5.0, {'a' , red } };
 

Input Buffer

EVAL s1

Receiver Variable

Step Statement Example

C Program Fragment

Assume program operation is suspended in the program shown in Figure 5 just before line 6 runs.

Figure 5. Program for Step Example

Line  C Source

 1    #include  stdio.h
 2    int T[] = {1,2,3,5,7,11,13,17,23,29};
 3    int BinarySearch(int v, int f, int l);
 4    main()
 5    { int result;
 6      result = BinarySearch(17,0,9);
 7      printf("result= "); printf("%d",result); printf(" \n");  
 8    }
 

Input Buffer

STEP

Receiver Variable

ATTR Statement Example

RPG Program Fragment

Consider the RPG program fragment in Figure 6. The fragment assigns 1 to a zoned(1,0) variable I.

The program is currently stopped at line 2.

Figure 6. RPG Programming Language Example, Evaluate

           CL0N01Factor1++++++OpcodeE+Extended-factor2

 1         C                  EVAL    I=1
 2         C                  MOVE    *ON          *INLR
 

Input Buffer

ATTR I

Receiver Variable

WATCH Statement Example

C Program Fragment

Consider the C program fragment in Figure 7. Variable i defines an integer.

Figure 7. Program for Scalar Evaluate Example

Line  C Source

 1    int i = 29;
 

Input Buffer

WATCH i

Receiver Variable

Error Messages

Debug Language Statements

Debug language statements are the principal mechanism by which a programmer debugs a program. Programmers control the operation of a program by:

• Entering break statements to select where the program will stop
  
  
• Entering step statements to run one or more statements of the program under investigation
  
  
• Entering watch statements to stop the program when a specified storage location is changed
  
  

The clear statement enables programmers to remove a particular breakpoint or all breakpoints. It can also be used to clear watches. Information about the state of the program being debugged can be extracted when program processing is suspended. The evaluate statement permits programmers to display the value of an expression, or to display an aggregate, and to alter the value of a variable.

Debug language statements are constructed by the client program and placed in the input buffer. If multiple debug language statements are placed in the input buffer, they must be separated by one or more blanks. The Submit Debug Command API accepts the debug language statements of ATTR, BREAK, CLEAR, EVAL, QUAL, SBREAK, STEP, TBREAK, and WATCH.

When multiple debug statements are specified in the same input buffer, a QUAL statement must not follow an EVAL statement. The WATCH debug statement cannot be specified with any other debug statement, including another WATCH statement.

ATTR Statement

The variable appearing in an ATTR statement is found in the debug symbol table. The symbol table information for the variable is returned.

The following example shows an ATTR statement:

The locality of variables that appear in an ATTR statement is defined by the most recently run qualify statement. The program calling this API is advised to issue a qualify statement that defines the stop position when program operation is suspended.

Break Statement

The break statement permits a programmer to enter a breakpoint. Breakpoints are entered on the program under investigation. When the program under investigation encounters a breakpoint, operation is suspended.

The following example shows a break statement:

The position marks where program operation is suspended when a breakpoint is encountered. Line numbers are used to identify the position when the break statement is entered. The line number entered is mapped to a statement by the Submit Debug Command API. A breakpoint causes the program to stop just before the break statement is run.

Unconditional and conditional breakpoints can be entered. Unconditional breakpoints are discussed first, followed by a discussion of conditional breakpoints.

An unconditional breakpoint is entered by issuing the first form of the break statement.

A line number is entered for the position. Line numbers are associated with each view in that they identify the lines of source in a view. Line numbers are assigned sequentially beginning with line one.

A conditional breakpoint is entered by issuing the second form of the break statement.

The position of a conditional breakpoint is assigned in the same way as the position in an unconditional breakpoint. A line number is entered for the position.

The condition of a conditional breakpoint is the expression following the reserved word WHEN. The result of the expression must have a Boolean or a logical value when evaluated. The expression is interpreted before the statement on which the breakpoint was entered is run. If the value of the expression is TRUE, operation of the program investigation is suspended. If the value of the expression is FALSE, operation continues without interruption.

The locality of variables used in the conditional expression is defined by the line number that defines the position.

A breakpoint can be replaced by entering another breakpoint using the same position. The most recent breakpoint entered on a position is the active breakpoint.

BREAK may be replaced by the reserved word AT in the statement that defines the break statement.

For threaded applications, breakpoints that are specified with the break statement are global to all threads in the job being debugged. These are called job breakpoints. Thread-specific breakpoints are set with the tbreak statement. A job may not have both a job breakpoint and thread breakpoints at the same position. When a job breakpoint is in effect and a thread breakpoint is specified, the job breakpoint is replaced. When thread breakpoints are in effect and a job breakpoint is specified, the thread breakpoints are replaced.

Clear Statement

The clear statement enables a programmer to remove a particular breakpoint or all breakpoints in a program. Particular breakpoints are identified by the number of the line on which they are active. All breakpoints in a program are designated by the keyword PGM. The clear statement is also used to clear one or all watch conditions. The keyword WATCH followed by the ALL keyword clears all watch conditions. If a watch number is specified after the WATCH keyword, only the watch represented by that watch number is cleared.

The following example shows a clear statement:

For threaded applications, if a thread breakpoint is in effect at the position specified, it is cleared in the current thread only. If the breakpoint is a job breakpoint, it is cleared for the job. When the clear statement with the PGM keyword is specified, it will remove all job and thread breakpoints.

Evaluate Statement

The expression appearing in an evaluate statement is evaluated, and the value of the expression is returned. The value of an expression is formatted according to the expression type.

The following example shows an evaluate statement:

An evaluate statement allows a programmer to display the value of an expression or an aggregate, or to alter the value of a variable. The precise definition of what can be displayed or altered is dependent on the language of the module being debugged.

Variables can be displayed or altered when program processing is suspended. Program operation is temporarily suspended as a result of encountering a breakpoint or completing a step statement. It is also suspended when a watch condition is satisfied.

Variables are formatted according to their type recorded in the HLL symbol table, and according to the language of the module being debugged. Formats available include integer, hexadecimal, exponential, and address, among others.

Variables also may be formatted using the formatting option. The formatting option has the general form of: :<format code> <length>, such as EVAL STRING :s 50.

The:<format code> can be one of the following:

The <length> is a positive integer that indicates the number of bytes to format. The defaults for the format codes are as follows:

Specification of the %LOCALVARS keyword will result in the evaluation of every variable originating in the current scope.

The locality of variables that appear in an evaluate statement is defined by the most recently run qualify statement. The program calling this API is advised to issue a qualify statement that defines the stop position when program operation is suspended.

EVAL may be replaced by the reserved word LIST in the statement that defines the evaluate statement.

The following table describes the formatting of data by type.

For threaded applications, the EVAL statement is run in the current thread.

Locality

Locality is the term used to describe the range over which an entity may be referred to in a module. The terms locality and scope are synonymous. By this definition, the locality of an entity is always confined to the compilation unit in which it was declared.

Entity is a formal way of describing all things that can be declared in a module. Variables, procedures, labels, types, and constants are entities.

The locality of an entity is defined by the block in which it is declared. An entity is visible in the block in which it is declared and all subordinate blocks. A variable can be referred to in the block in which it is declared.

An entity may be declared in a block that encloses other blocks. The entity declared in the outer, enclosing block is visible in inner blocks if the name does not collide with other entities in inner blocks. A variable declared in an outer block can be referred to in an inner block if no variable of the same name is declared in the inner block.

To fully qualify a particular locality in a program, both program and module must be identified.

Qualify Statement

The qualify statement permits a programmer to define the locality of variables that appear in succeeding evaluate statements. Locality is defined by the line number operand on the qualify statement. The locality assigned is that block in which the line number appears.

The following example shows a qualify statement:

The locality assigned when a qualify statement is issued remains in effect until the next qualify statement is issued. The Submit Debug Command API keeps the locality assigned for the purpose of evaluating expressions. Users of the Submit Debug Command API are advised to issue the qualify statement whenever program operation is suspended. Use the line number of the stopped position to identify the current locality. In this way, programmers may issue several evaluate statements that refer to variables that are defined in the locality of the stopped position.

For threaded applications, the QUAL statement is run in the current thread.

SBreak Statement

The sbreak statement permits a programmer to enter a service entry breakpoint. Service entry breakpoints are entered on the program about to be spawned by another program. When the spawned program encounters a service entry breakpoint, operation is suspended.

The following example shows a sbreak statement:

The position marks where program operation is suspended when a service entry breakpoint is encountered. Line numbers are used to identify the position when the sbreak statement is entered. The line number entered is mapped to a statement by the Submit Debug Command API. A service entry breakpoint causes the program to stop just before the sbreak statement is run.

The userid specifies the user profile under which a job must be executing for the service entry point being set to be active in that job. If the userid is not specified, it defaults to the user profile under which the job in which the sbreak command is issued is running.

A service entry point, job breakpoint or thread breakpoint cannot exist at the same time at the same position. Only one of the three types of breakpoints may exist at a specified position. If the sbreak command is issued for a position in which one of the three types of breakpoints already exists, the existing breakpoint will be replaced by the service entry point.

Step Statement

The step statement permits a programmer to run one or more statements of the program under investigation for testing purposes. The program being tested runs the number of statements specified in the statement-count operand. Operation of the program under test is suspended at completion of the step statement.

The following example shows a step statement:

If no value is entered for the statement-count, one statement is run.

The reserved words OVER and INTO direct the source debugger to step over or into procedures, respectively. If OVER appears in a step statement, the source debugger does not suspend operation in any procedures that are called. Procedures and functions are run without interruption.

The INTO reserved word directs the source debugger to stop in procedures that are called.

If neither INTO or OVER is entered on the step statement, OVER is assumed.

There are some step limitations. The following code cannot be entered using the step statement:

• Procedures in modules that have no debug data.
  
  
• Modules that are optimized at level 40.

For threaded applications, the STEP statement is run in the current thread. Each thread can step independently of each other, at the same time.

TBreak Statement

The tbreak statement permits a programmer to enter a breakpoint for the current thread. Breakpoints are entered on the program under investigation. When the program under investigation encounters a breakpoint in the thread, operation is suspended. The tbreak statement has the same format and operation as the break statement.

Each thread in a threaded application may have a different thread breakpoint at the same position. Job breakpoints and thread breakpoints cannot coexist.

A tbreak statement entered at the same position as a tbreak that was specified earlier in the same thread is replaced by the new thread breakpoint.

A tbreak statement entered at the same position as a job breakpoint that was specified earlier replaces the job breakpoint with a thread breakpoint.

A break statement entered at the same position as thread breakpoints that were specified earlier replaces all thread breakpoints at that position with a job breakpoint that is in effect for all threads.

Watch Statement

The watch statement permits a programmer to request a breakpoint when the content of a specified storage location is changed from its current value. After the watch condition is successfully set, a change to the content of the watched storage location causes program operation to be suspended. Then the Program Stop Handler exit program that is specified on the Start Source Debug API is called.

The following shows the syntax of the watch statement:

The expression is used to determine the address of the storage location to watch. The expression must resolve to an lvalue (that is, a location that can be assigned to). If an expression is specified that is not supported, error code CPF7E62 is returned. The scope of the expression variables in a watch statement is defined by the most recently issued QUAL debug language statement.

The length of the watch comparison operation is the same as the expression type length, or the length specified with the optional watch length parameter. For example, if a 4-byte binary integer is specified without the watch length parameter, the comparison length is 4 bytes. If the watch length parameter is specified, it overrides the length of the expression in determining the watch length. The watch length specification format is a colon character followed by the length in bytes to watch. For example, the watch command below would watch 2 bytes starting at the first byte of variable i:

watch i : 2

The watch length must be in the range 1 through 128 bytes. If the watch length is not valid, error code CPF7E63 is returned.

The maximum number of watches that can be active across the entire system is guaranteed to be at least 128, but may range up through 256, depending on how the watched storage is mapped by the system. This includes dedicated service tools (DST) watches. Exceeding this number results in error code CPF8E2C being returned. A user session may have as many watches as are available.

There are some restrictions on overlapping watch locations. If any of the following conditions are true, error code CPF8E2B is returned:

• Watches in same job: Two watch locations may not overlap in any way.
  
  
• Watches in different jobs: Two watch locations may not start at the same storage address. Otherwise, overlap is permitted.

A watch condition is cleared by using the CLEAR debug language statement.

It is important to understand that the watch statement establishes the watched storage location address when the watch statement is entered, and it does not change. This can cause misleading results if a temporary storage location is watched and that storage location is reused while the application is running. An example of this is the automatic storage of an ILE C procedure, which can be reused if the procedure ends.

The WATCH debug statement cannot be specified with any other debug statement, including another WATCH statement.

For threaded applications, the WATCH statement is run in the current thread. The address watched is global to all threads. Any thread changing a watched location will cause a breakpoint in that thread.

[ Back to top | Debugger APIs | APIs by category ]