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.

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The variable that is to receive the results of the Submit Debug Command API. For more information on the structure of the receiver variable, see Table 7.

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 Table 7, 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 on the fields contained in the table, see Field Descriptions.

Table 6. Receiver Variable Structure

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Bytes returned
4	4	BINARY(4)	Bytes available
8	8	BINARY(4)	Entry count
12	C	CHAR(*)	Results array
		CHAR(*)	String space

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. Table 7 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 Table 7.

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

Table 7 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

Table 7. Variations in Receiver Variable Structure

Header	Bytes Returned	Bytes Available	Entry Count
Result array 1	Result type
Result array 2	Result type	Count
Result array 3	Result type	Offset	Length
String space

Each row of Table 7 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.

• The last row of Table 7 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 Table 7 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.

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Result type
4	4	BINARY(4)	Step count
8	8	CHAR(4)	Reserved

BreakR (2)

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

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Result type
4	4	BINARY(4)	Break results count
8	8	CHAR(4)	Reserved

ClearBreakpointR (3)

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

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Result type
4	4	BINARY(4)	Line number
8	8	CHAR(4)	Reserved

ClearPgmR (4)

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

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Result type
4	4	CHAR(4)	Reserved
8	8	CHAR(4)	Reserved

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.

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Result type
4	4	BINARY(4)	Line number
8	8	CHAR(4)	Reserved

EvaluationR (6)

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

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Result type
4	4	BINARY(4)	Evaluation count
8	8	BINARY(4)	Reserved

ExpressionTextR (7)

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

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Result type
4	4	BINARY(4)	Expression text offset
8	8	BINARY(4)	Expression text length

ExpressionValueR (8)

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

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Result type
4	4	BINARY(4)	Expression value offset
8	8	BINARY(4)	Expression value length

ExpressionTypeR (9)

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

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Result type
4	4	BINARY(4)	Expression type
8	8	CHAR(4)	Reserved

QualifyR (10)

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

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Result type
4	4	BINARY(4)	Line number
8	8	BINARY(4)	Reserved

TypeR (11)

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

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Result type
4	4	BINARY(4)	Type record count
8	8	BINARY(4)	Reserved

TypeDescR (12)

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

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Result type
4	4	BINARY(4)	Type
8	8	BINARY(4)	Length

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.

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Result type
4	4	BINARY(4)	Total digits
8	8	BINARY(4)	Fraction digits

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.

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Result type
4	4	BINARY(4)	Dimensions
8	8	BINARY(4)	Reserved

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.

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Result type
4	4	BINARY(4)	Low bound
8	8	BINARY(4)	High bound

WatchR (16)

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

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Result type
4	4	BINARY(4)	Watch results count
8	8	BINARY(4)	Reserved

WatchNumberR (17)

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

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Result type
4	4	BINARY(4)	Watch number
8	8	BINARY(4)	Watch length

ClearWatchNumberR (18)

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

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Result type
4	4	BINARY(4)	Watch number
8	8	BINARY(4)	Reserved

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.

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Result type
4	4	BINARY(4)	Reserved
8	8	BINARY(4)	Reserved

TBreakR (20)

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

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Result type
4	4	BINARY(4)	TBreak results count
8	8	CHAR(4)	Reserved

Field Descriptions

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

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:

Type	Enumeration	Description
0	kNoType__E	Type is not valid
1	kChar__8_E	8-bit character value
2	kChar_16_E	16-bit character value
3	kBool_32_E	32-bit Boolean value
4	kCard_16_E	16-bit unsigned integer value
5	kCard_32_E	32-bit unsigned integer value
6	kInt__16_E	16-bit two's complement integer value
7	kInt__32_E	32-bit two's complement integer value
8	kReal_32_E	32-bit real floating-point value
9	kReal_64_E	64-bit real floating-point value
10	kSpcPtr__E	128-bit pointer
11	kFncPtr__E	128-bit function pointer
12	kMchAddr_E	128-bit machine pointer
13	kRecord__E	Structure or record
14	kArray___E	Array
15	kEnum____E	Enumerated type
16	kString__E	String (:s format on EVAL)
17	kPacked__E	Packed decimal
18	kZonedTE_E	Zoned, trailing embedded sign
19	kZonedTS_E	Zoned, trailing separate sign
20	kZonedLE_E	Zoned, leading embedded sign
21	kZonedLS_E	Zoned, leading separate sign
22	kBinD_16_E	16-bit binary decimal value
23	kBinD_32_E	32-bit binary decimal value
24	kBinD_64_E	64-bit binary decimal value
25	kTable___E	Multiple occurrence data structure
26	kInd_____E	Indicator
27	kDate____E	Date
28	kTime____E	Time
29	kTstamp__E	Timestamp
30	kFixedL__E	Fixed-length string
31	kStringF_E	String (:f, :a, :u format on EVAL command)
100	kHex_____E	Hexadecimal (:x format on EVAL command)

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.

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.

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.

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 OS/400 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.

• An Expression type record is returned, which contains the type 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 section 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 Table 8 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.

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 OS/400 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 OS/400 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 (&O/;) 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

Bytes returned
Bytes available
Entry count

59
59
3

Result type
Break results count
Reserved

BreakR
3
 

Result type
Line number
Reserved

BreakPositionR
7

Result type
Expression text offset
Expression text length

ExpressionTextR
48
10

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

Bytes returned
Bytes available
Entry count

65
65
4

Result type
Evaluation count
Reserved

EvaluationR
4
 

Result type
Expression text offset
Expression text length

ExpressionTextR
60
1

Result type
Expression value offset
Expression value length

ExpressionValueR
62
2

Result type
Expression type
Reserved

ExpressionTypeR
kInt__32_E
 

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

Bytes returned
Bytes available
Entry count

64
64
4

Result type
Evaluation count
Reserved

EvaluationR
4
 

Result type
Expression text offset
Expression text length

ExpressionTextR
60
1

Result type
Expression value offset
Expression value length

ExpressionValueR
62
1

Result type
Expression type
Reserved

ExpressionTypeR
kZonedTE_E

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

Bytes returned
Bytes available
Entry count

246
246
16

Result type
Evaluation count
Reserved

EvaluationR
4
 

Result type
Expression text offset
Expression text length

ExpressionTextR
204
4

Result type
Expression value offset
Expression value length

ExpressionValueR
209
1

Result type
Expression type
Reserved

ExpressionTypeR
kInt__32_E
 

Result type
Evaluation count
Reserved

EvaluationR
4
 

Result type
Expression text offset
Expression text length

ExpressionTextR
211
4

Result type
Expression value offset
Expression value length

ExpressionValueR
216
7

Result type
Expression type
Reserved

ExpressionTypeR
kReal_64_E
 

Result type
Evaluation count
Reserved

EvaluationR
4
 

Result type
Expression text offset
Expression text length

ExpressionTextR
224
7

Result type
Expression value offset
Expression value length

ExpressionValueR
232
1

Result type
Expression type
Reserved

ExpressionTypeR
kChar__8_E
 

Result type
Evaluation count
Reserved

EvaluationR
4
 

Result type
Expression text offset
Expression text length

ExpressionTextR
234
7

Result type
Expression value offset
Expression value length

ExpressionValueR
242
3

Result type
Expression type
Reserved

ExpressionTypeR
kEnum____E
 

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

Bytes Returned
Bytes Available
Entry Count

24
24
1

Result type
Step Count
Reserved

StepR
1
 

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

Bytes returned
Bytes available
Entry count

48
48
3

Result type
Type record count
Reserved

TypeR
3
 

Result type
Type
Length

TypeDescR
kZonedTE_E
1

Result type
Total digits
Fractional digits

DecimalR
1
0

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

Bytes returned
Bytes available
Entry count

83
83
4

Result type
Watch results count
Reserved

WatchR
4
 

Result type
Watch number
Watch length

WatchNumberR
1
4

Result type
Expression text offset
Expression text length

ExpressionTextR
60
1

Result type
Expression value offset
Expression value length

ExpressionValueR
62
20

Error Messages

CPF1938 E

Command is not allowed while serviced job is not active.

CPF1939 E

Time-out occurred waiting for a reply from the serviced job.

CPF1941 E

Serviced job has completed. Debug commands are not allowed.

CPF3C19 E

Error occurred with receiver variable specified.

CPF3C24 E

Length of the receiver variable is not valid.

CPF3CF1 E

Error code parameter not valid.

CPF7102 E

Unable to add breakpoint or trace.

CPF7E01 E

Pointer to receiver variable is NULL.

CPF7E02 E

Receiver variable length not valid.

CPF7E03 E

Pointer to input buffer is NULL.

CPF7E04 E

Input buffer length not valid.

CPF7E05 E

Input buffer is not as long as specified.

CPF7E06 E

Pointer to error code structure is NULL.

CPF7E07 E

Not enough space was provided for error code.

CPF7E08 E

Value of BytesProvided field is not correct.

CPF7E09 E

Value of BytesProvided field, &1, is not correct.

CPF7E10 E

Internal error occurred.

CPF7E11 E

Type error occurred.

CPF7E12 E

Identifier does not exist.

CPF7E14 E

Field does not exist.

CPF7E15 E

Syntax error occurred.

CPF7E16 E

Token error occurred.

CPF7E17 E

Structure type error occurred.

CPF7E18 E

Pointer type error occurred.

CPF7E19 E

Integral type error occurred.

CPF7E1A E

Enumerated type error occurred.

CPF7E1B E

Arithmetic type error occurred.

CPF7E1C E

Scalar type error occurred.

CPF7E1D E

Address type error occurred.

CPF7E1E E

Adding type error occurred.

CPF7E1F E

Subtracting type error occurred.

CPF7E20 E

Relational type error occurred.

CPF7E21 E

Equality type error occurred.

CPF7E22 E

Casting type error occurred.

CPF7E23 E

Assignment type error occurred.

CPF7E24 E

Line number not found.

CPF7E25 E

Array type error occurred.

CPF7E26 E

Subscript type error occurred.

CPF7E27 E

Format type error occurred.

CPF7E28 E

Type error occurred.

CPF7E29 E

Unsupported bit field alignment

CPF7E2A E

String constants are not supported.

CPF7E2B E

Type compatibility error occurred.

CPF7E2C E

Too few array dimensions specified.

CPF7E2D E

Too many array dimensions specified.

CPF7E2E E

Incorrectly formed range expression

CPF7E2F E

Range expression expands to exceed input buffer

CPF7E50 E

Decimal type error occurred.

CPF7E51 E

Decimal size error occurred.

CPF7E52 E

Unsupported syntax.

CPF7E53 E

Assignment size error occurred.

CPF7E54 E

Integer type error occurred.

CPF7E55 E

Constant type error occurred.

CPF7E56 E

Identifier is ambiguous.

CPF7E57 E

Integer constant not valid.

CPF7E58 E

Compiler not valid.

CPF7E59 E

String type error occurred.

CPF7E5A E

Substring extends beyond end of string.

CPF7E5B E

Format length error occurred.

CPF7E5C E

Hexadecimal constant not valid.

CPF7E5D E

Decimal constant size error occurred.

CPF7E5E E

Integer constant size error occurred.

CPF7E5F E

Relational size error occurred.

CPF7E60 E

Constant not a decimal number.

CPF7E61 E

System cannot determine which expansion of the template to use.

CPF7E62 E

Watch cannot be set on this variable.

CPF7E63 E

Watch length is not valid.

CPF7E64 E

Clear watch number not found.

CPF8E03 E

Internal error occurred.

CPF8E04 E

Internal error occurred.

CPF8E05 E

Error on equal operator.

CPF8E06 E

Error on not-equal operator.

CPF8E07 E

Error on greater-than operator.

CPF8E08 E

Error on greater-than-or-equal-to operator.

CPF8E09 E

Error on less-than operator.

CPF8E0A E

Error on less-than-or-equal-to operator.

CPF8E0B E

Error on logical-and operator.

CPF8E0C E

Error on logical-or operator.

CPF8E0D E

Error on logical-exclusive-or operator.

CPF8E0E E

Error on logical-not operator.

CPF8E0F E

Error on add operator.

CPF8E10 E

Error on subtract operator.

CPF8E11 E

Error on negate operator.

CPF8E12 E

Error on multiply operator.

CPF8E13 E

Error on divide operator.

CPF8E14 E

Error on increment operator.

CPF8E15 E

Error on decrement operator.

CPF8E16 E

Error on modulo operator.

CPF8E17 E

Pointer not set for location referenced.

CPF8E18 E

Conversion error.

CPF8E19 E

Error on absolute value operator.

CPF8E1A E

Domain violation occurred.

CPF8E1B E

Domain violation occurred.

CPF8E1C E

Error on write operator.

CPF8E1D E

Error on shift operator.

CPF8E1E E

Error on operand value.

CPF8E1F E

Error on load constant operator.

CPF8E20 E

Error on load address operator.

CPF8E21 E

Error on store indirect operator.

CPF8E22 E

Error on move operator.

CPF8E23 E

Error on fill operator.

CPF8E24 E

Incorrect array index value.

CPF8E25 E

Call stack entry does not exist.

CPF8E26 E

Translation failed.

CPF8E27 E

Call to user method failed.

CPF8E28 E

Variable not available to display.

CPF8E29 E

Debug recursion error.

CPF8E2A E

Error occurred while processing operation.

CPF8E2B E

Watch cannot overlap another active watch.

CPF8E2C E

Maximum number of watches exceeded.

CPF9541 E

Not in debug mode.

CPF9542 E

View not found.

CPF9549 E

Error addressing API parameter.

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

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, 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:

Format

Description

Code

:c

An EBCDIC single-character format

:x

A hexadecimal format

:s

An EBCDIC character-string format (only for the C and C++ languages)

:f

An EBCDIC character-string format (only for the C and C++ languages). This returned type can be used by the source debugger to indicate that alternative formatting was requested by the user.

:a

An ASCII character-string format (only for the ILE languages). The string is converted from the job CCSID's related-ASCII CCSID to the job CCSID.

:u

A Unicode character-string format (only for ILE languages). The string is converted from Unicode CCSID 13488 to the job CCSID.

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

Format

Default

Code

:c

1

:x

The length of the expression value

:s

30

:f

1024

:a

1024

:u

1024

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.

Table 8 describes the formatting of data by type.

Table 8. Presentation Formats

Type	Format	Example
kChar__8_E	c	A
kChar_16_E	Shift-out cc... shift-in
kEnum____E	ccccc (dd)	yellow (25)
kString__E	ccccccccc	Hello World
kInt_32__E	-dd...d dd...d	-676
kPacked__E	dd.ddd -dd.ddd	5678.01
kZonedTE_E	dd.ddd -dd.ddd	5678.01
kZonedTS_E	dd.ddd -dd.ddd	5678.01
kZonedLE_E	dd.ddd -dd.ddd	5678.01
kZonedLS_E	dd.ddd -dd.ddd	5678.01
kBinD_16_E	dd.ddd -dd.ddd	5678.01
kBinD_32_E	dd.ddd -dd.ddd	5678.01
kBinD_64_E	dd.ddd -dd.ddd	5678.01
kFixedL__E	ccccc	Hello World
kHex_____E	xx xx xx xx	F1 F2 F3
kCard_32_E	dd...d	546
kReal_64_E	+d.d...dE+dd -d.d...dE-dd	-1.2345678901234E-95
KSpcPtr__E	Pointer types: BEP (behavior) IVP (invocation) LBL (label) MTP (method) OBP (object) PRP (procedure) SPP (space) SYP (system)	SPP:*NULL IVP:COFE001001201003 SPP:COCE100201021003

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.

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.