Retrieve View Text (QteRetrieveViewText) API

The Retrieve View Text (QteRetrieveViewText) API is used to retrieve source text from a specified view. This text may be formatted and displayed by the user of this API. The caller must specify the following:

• A registered view ID
  
  
• The starting line number to be retrieved
  
  
• The number of lines of text to retrieve
  
  
• A buffer to contain the text retrieved

All text retrieved, whether it comes from files or as text supplied by a processor, is in the CCSID of the job.

If source files have changed since the view was created, diagnostic messages CPF9561 (for i5/OS files) and CPF9596 (for i5/OS integrated file system files) are sent to the calling program's message queue for each file. Error messages CPF9566 (for i5/OS files) and CPF9597 (for i5/OS integrated file system files) also are issued, and all of the text available is retrieved. The calling program should warn the user that the view text may be incorrect.

If a source file cannot be accessed because it is deleted or the user is not authorized, error messages CPF9565 (for i5/OS files) and CPF9598 (for i5/OS integrated file system files) are issued. No more text is retrieved. Text up to that file is retrieved and this is indicated in the fields of the receiver variable. If the calling program attempts to read text in the view following the file, the starting line number can be set to a line after the file. The number of lines in the file that should have been read is returned in the exception data. This allows the calling program to skip over this file if desired.

It is suggested that the calling program buffer the retrieved text to minimize use of this API. Source files accessed by this API do not remain open across API calls. Performance degradation occurs for every use of the API that results in file access because of opening and closing files.

Authorities and Locks

None.

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The variable that is to receive the information requested. You can specify the size of this area to be smaller than the format requested if you specify the length of receiver variable 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 parameter. The minimum length is 8 bytes.

View ID

INPUT; BINARY(4)

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

Start line number

INPUT; BINARY(4)

The number of the first line to be retrieved.

Number of lines

INPUT; BINARY(4)

The number of lines of source text to be retrieved. This number includes the line specified in the start line number parameter. Fewer than the number of lines may be placed in the receiver variable if fewer lines than requested are available. 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 of the text associated with this view should be retrieved.

Line length

INPUT; BINARY(4)

The length of each line of text to be retrieved. Each line takes exactly this many characters. If the actual line of text is shorter, it is padded to the right with blanks. If the line is longer than this length, it is truncated to fit. The line length must be a number from 1 through 255.

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 following tables show the information supplied in the receiver variable parameter. The information returned depends on the type of view being used. For more information on each field, see Field Descriptions. For the listing view:

For the statement view:

For the text view:

Field Descriptions

Bytes available. The number of bytes of data available to be returned.

Bytes returned. The number of bytes of data returned.

Line length. The length of each line of text in the receiver variable parameter.

Listing view source line. The text associated with each line retrieved. The number of characters in each line is equal to the line length.

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

Procedure dictionary number. The number that uniquely identifies the procedure in this module. The number is left-justified and padded on the right with blanks. For OPM programs the procedure dictionary number is set to a value of 0.

Procedure name. The name of the procedure. The name is left-justified and padded on the right with blanks. For OPM programs the procedure name is blanks.

Sequence number. If the text is from a source physical file, these 12 bytes contain the sequence number and source date for that line. If the text is from an i5/OS integrated file system file, these 12 bytes are blank. If the text is supplied by the compiler, these 12 bytes are blank.

Statement number. The number that uniquely identifies the statement in the procedure. The number is left-justified and padded on the right with blanks. 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 number. The type of statement produced by the compiler. The number is left-justified and padded on the right with blanks. Possible values are:

Text view source line. The text associated with each line retrieved. The number of characters in each line equals the line length minus 12 bytes (the sequence number).

Error Messages