Retrieve View Line Information (QteRetrieveViewLineInformation) API

The Retrieve View Line Information (QteRetrieveViewLineInformation) API is used to retrieve information about a specified number of lines in a registered view.

The data returned to the caller of the API indicates whether a given line or range of lines within a view can be run or not.

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.

See RTVL0100 Format for details on the format of the receiver variable.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable provided by the receiver variable parameter. If this value is larger than the actual amount of storage allocated for the receiver variable, the results are not predictable. The minimum length is 8 bytes.

Format name

INPUT; CHAR(8)

The format of the information returned. The possible format names are:

RTVL0100

Retrieve view line information.

View ID

INPUT; BINARY(4)

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

Start line number

INPUT; BINARY(4)

The number of the first line in the view for which the API is to retrieve information. This must be greater than or equal to 1 and less than or equal to the total number of lines in the view.

Number of lines

INPUT; BINARY(4)

The number of lines in the view for which the API is to retrieve information. This number includes the line specified in the start line number parameter. Fewer than number of lines elements may be placed in the receiver variable if fewer lines than requested are available. No more than number of lines elements are placed in the receiver variable.

The following special values are supported for this parameter:

-1

All lines associated with this view starting at the value specified for the start line number parameter should be processed.

Error code

I/O; CHAR(*)

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

RTVL0100 Format

For a description of the fields in the receiver variable, see Field Descriptions.

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Bytes returned
4	4	BINARY(4)	Bytes available
8	8	BINARY(4)	Offset to line information array
12	C	BINARY(4)	Number of line information array elements
16	10	BINARY(4)	Length of line information array element
		CHAR(*)	Reserved
Note: The following fields describe an element in the line information array and are repeated the "number of line information array elements" times. The nth element of the array (n > 0) describes the start line number + n-1 line in the view, where start line number is a parameter to this API.
		CHAR(1)	Line disposition
		CHAR(*)	Reserved

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.

Length of line information array element. The number of bytes occupied by a single element of the line information array. Line information array elements are contiguous and all have the same length.

Line disposition. Whether the line in the view described by this array element can be run or not. Possible values are:

0

Line cannot be run

1

Line can be run

Number of line information array elements. The number of elements in the line information array that were returned by this API.

Offset to line information array. The offset (in bytes) from the start of the receiver variable to the first element of the line information array.

Reserved. An ignored field.

Error Messages

CPF3C21 E

Format name &1 is not valid.

CPF3C24 E

Length of the receiver variable is not valid.

CPF3CF1 E

Error code parameter not valid.

CPF3CF2 E

Error(s) occurred during running of &1 API.

CPF9541 E

Not in debug mode.

CPF9542 E

View not found.

CPF9549 E

Error addressing API parameter.

CPF9564 E

Starting line number not valid.

CPF957A E

Number of lines not valid.

CPF957B E

Required information not found for operation.