Retrieve Statement View (QteRetrieveStatementView) API

The Retrieve Statement View (QteRetrieveStatementView) API is used to retrieve the statement view and related information. The statement view information that is retrieved can be useful for breakpoint processing. The caller must specify the following:

• The registered statement view ID
  
  
• The starting statement view line number to be retrieved
  
  
• The number of statement view lines to retrieve
  
  
• A buffer to contain the statement view and related information

Authorities and Locks

None.

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold. For more information, see Format of Receiver Variable.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable provided. The length of receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. The minimum length is 8 bytes.

View ID

INPUT; BINARY(4)

The identifier of the previously registered statement view obtained by using the Register Debug View (QteRegisterDebugView) API.

Start line number

INPUT; BINARY(4)

The number of the first statement view line that the API is to retrieve. Statement view lines begin at line 1.

Number of lines

INPUT; BINARY(4)

The number of lines of the statement view to be retrieved. This number includes the line specified in the start line number parameter. If fewer lines than requested are available, the number of lines placed in the receiver variable may be less than the number specified. No more than the number of lines specified is placed in the receiver variable.

The following special value is supported for this parameter:

0	All lines from the start line number to the end of the statement view should be retrieved.

Error code

I/O; CHAR(*)

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

Format of Receiver Variable

The receiver variable consists of:

• A receiver variable header section.
  
  
• A section containing the statement view lines.
  
  
• A section containing information for each procedure in the statement view.
  
  
• A string space containing the statement view procedure names.
  
  
• A section containing offsets to additional information about individual statement view lines.
  
  
• A section containing additional information about individual statement view lines.
  
  
• A space containing variable length fields that are referenced by other returned data sections.

Variables containing offsets are used to access statement view data. All offsets are relative to the beginning of the receiver variable.

Receiver Variable Header Section

The following table shows the information supplied in the receiver variable parameter. For more information on each field, see Field Descriptions.

Statement View Section

The statement view is returned as an array of statement lines. The first statement view line can be accessed by using the first view line offset in the receiver header. The number of lines returned variable in the receiver header is used to tell how many statement lines were returned. The total number of bytes in each line is equal to the line length. Each line has the following format.

Procedure Information Section

The procedure information section contains one variable-length data structure for each procedure in the statement view. The first procedure information data structure can be accessed by using the first procedure information offset in the receiver header. Each statement view line contains a statement procedure information offset that can be used to locate procedure information for the statement line. Each procedure information data structure has the following format.

Procedure Name String Space

The procedure name string space contains the text of the procedure names in the module. The procedure name offset in the procedure information section is used to access a procedure name. The procedure name length is also contained in the procedure information section. The procedure name is converted to the coded character set identifier (CCSID) of the job.

Statement-View-Line Additional-Information Offsets Section

If the compiler supplies it, additional information is returned for individual statement view lines. For example, a statement may have a name associated with it, such as a block or label name. Each line in the statement view section has a corresponding offset to additional information for the line. Thus, the first offset in this section is used to find the additional information for the first statement view line returned. The second offset will reference additional information for the second statement view line returned, and so on. There must be space in the receiver variable for the additional-information offsets of all statement view lines returned or none of the offsets is returned. The presence of this section is indicated by a nonzero value in the offset to first statement-view-line additional-information offset in the receiver header. If this section is present, there is one offset for each statement view line returned. If there is additional information for a statement view line, the additional information offset for it is nonzero. Each offset has the following format.

Statement-View-Line Additional-Information Section

If the compiler supplies it, additional information is returned for individual statement view lines. For example, a statement may have a name associated with it, such as a block or label name. The statement-view-line additional-information section contains one variable-length data structure for each statement view line that has additional information associated with it. If there is not enough room in the receiver variable for all of the additional-information data structures to be returned, the number that fits is returned. The additional information data structures are referenced by the offsets in the statement-view-line additional-information offsets section. Each additional-information data structure has the following format.

Variable Length Field Section

This section contains space to return variable length fields. These fields are referenced by other returned data structures through offsets. Usually, a length field would also be contained within the same data structure that references a field in this 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.

High line number. The high view-line number in the statement view of a procedure statement range.

Length of procedure name. The length of the procedure name in the procedure string space. For OPM programs the procedure name length is set to a value of 1.

Length of statement name. The length of the statement name associated with the statement view line.

Length of statement view line. The length of each statement view line in the statement view section.

Low line number. The low view-line number in the statement view of a procedure statement range.

Number of lines returned. The number of statement view lines retrieved by this API. This may be less than the number of lines requested or available if the receiver variable is not large enough to hold the number of lines requested.

Number of statement line ranges. The number of statement view line ranges in the procedure information data structure.

Offset to first procedure information structure. The displacement from the start of the receiver variable to the first procedure information data structure in the procedure information section. This value is zero when no procedure information is returned because of insufficient receiver variable space.

Offset to first statement line range element. The displacement from the start of the receiver variable to the first statement range element in the procedure information data structure.

Offset to first statement view line. The displacement from the start of the receiver variable to the first statement view line. This value is zero if no statement view lines are returned because of insufficient receiver variable space.

Offset to first statement-view-line additional-information offset. The displacement from the start of the receiver variable to the first statement-view-line additional-information offset. This value is zero if no statement-view-line additional-information offsets are returned because of insufficient receiver variable space, or if the compiler does not support debug data for additional statement view lines.

Offset to next procedure information structure. The displacement from the start of the receiver variable to the next procedure information data structure. This value is zero when there are no more procedure information data structures.

Offset to procedure name. The displacement from the start of the receiver variable to the procedure name. This value is zero if the procedure name is not returned because it would not fit in the procedure string space.

Offset to statement name. The displacement from the start of the receiver variable to the statement name that is associated with the statement view line. For example, this could be a block or label name. This value is zero if the statement name is not returned because it would not fit in the variable length field section, or because the compiler did not provide a statement name.

Offset to statement procedure information structure. The displacement from the start of the receiver variable to appropriate procedure information data structure in the procedure information section. This value is zero if the procedure information for this statement was not returned because of insufficient receiver-variable space.

Offset to statement-view-line additional information. The displacement from the start of the receiver variable to the statement-view-line additional-information data structure. This value is zero if no statement-view-line additional information is returned because of insufficient receiver variable space, or because there is no additional information for the statement view line.

Procedure dictionary number. The number that uniquely identifies the procedure in this module. For OPM programs the procedure dictionary number is set to a value of 0.

Procedure name. The name of the procedure. The procedure name is converted to the CCSID of the job. For OPM programs the procedure name is set to a blank value with a length of 1 byte.

Statement number. The number that uniquely identifies the statement in the procedure. This number is shown on the compiler listing. For OPM programs the statement number is the same as the machine interface (MI) number.

Statement type. The type number of statement produced by the compiler. Possible values are as follows:

Variable length field. A field referenced by an offset in a returned data structure. The data type is determined by where it is referenced. For example, a statement name field is a text string.

Error Messages