Retrieve Program Variable (QTERTVPV) API

The Retrieve Program Variable (QTERTVPV) API retrieves the current value of one program variable in a program that is being debugged. The information is returned to the calling program in a receiver variable. The amount of returned information is limited to the size of the receiver variable. This information is similar to the information returned using the Display Program Variable (DSPPGMVAR) command.

Restriction

This API is valid only in debug mode and supports original program model (OPM) programs only. It cannot be used if the user is servicing another job and that job is on a job queue, or is held, suspended, or ended.

Authorities and Locks

None.

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The variable that is to receive the information requested. The minimum size for this area is 8 bytes. If the size of this area is smaller than the available information, the API returns only the data that the area can hold.

See Format of Receiver Variable for details about the format.

Length of receiver variable

INPUT; BINARY(4)

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

Program variable

INPUT; CHAR(132)

The name of the program variable whose value is to be retrieved. Possible values follow:

*CHAR	This special value is specified instead of a variable name if a basing pointer is also specified. This special value returns a character view of the area addressed by a pointer.
Program variable name	The name of the program variable. For information about program variables, see the topic on program-variable description in the Control Language (CL) information.

Basing pointer

INPUT; ARRAY(5) of CHAR(132)

In languages where a program variable may be based on a pointer variable, you can specify the basing pointers for the variable to be retrieved. Up to five basing pointers may be specified. If the basing pointer is an element in an array, the subscript representing an element in the array must be specified. Up to 132 characters can be specified for one basing pointer name. If no basing pointer is specified, then the structure must be initialized to blanks. If one or more basing pointers are specified, then the subsequent array entries must be initialized to blanks. For more information on basing pointers, refer to the topic on basing-pointer description in the Control Language (CL) information in the iSeries Information center.

Starting position

INPUT; BINARY(4)

For string variables only, the starting position in the string from which its value is being retrieved. For a bit string, the value is the starting bit position. For a character string, the value is the starting character position.

This parameter is ignored on nonstring variables but must be initialized to any number greater than 0.

Length of string

INPUT; BINARY(4)

For string variables only, the length of the string retrieved, starting at the position specified by the start parameter. For a bit string, this value is the number of bits to retrieve. For a character string, this value is the number of characters to retrieve.

0	The value of the string variable is retrieved to the end of the string or retrieved for 200 bytes, whichever is less. If the string variable has a maximum length of zero, only 0 is allowed.
Retrieve length	The length of data to retrieve. This parameter is ignored on nonstring variables but must be initialized to any number 0 or greater.

Output format

INPUT; CHAR(10)

The format in which the value is to be returned.

*CHAR	The value of the program variable is returned in character form.
*HEX	The value of the program variable is returned in hexadecimal form.

Program

INPUT; CHAR(10)

The name of the program that contains the program variable to be retrieved.

*DFTPGM	The program currently specified as the default program will be used.
Program name	The name of the program whose program variable is retrieved.

Recursion level

INPUT; BINARY(4)

The recursion level of the program that contains the program variable.

0	The last (most recent) call of the program is the one from which the automatic program variable is retrieved.
n	The number of the recursion level of the program from which the automatic program variable is retrieved.

This parameter is ignored on static variables but must be initialized to any number 0 or greater.

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 table shows the information supplied in the receiver variable parameter. For more information on each field, see Field Descriptions.

The following tables show the information supplied in the data retrieved field. The variable type field, which is enclosed in parentheses, indicates which table is used.

Data for Binary Numeric (1)

Data for Floating Point (2)

Data for Zoned Decimal (3)

Data for Packed Decimal (4)

Data for Fixed Character (5)

Data for Varying Character (6)

Data for Fixed Bit (7)

Data for Unsigned Binary (8)

Data for Space Pointer (9)

Data for Data Pointer (10)

Data for Instruction Definition List (11)

Data for System Pointer (12)

Data for Machine Space Pointer (13)

Data for Exception Description (14)

Field Descriptions

Array of messages. An array of the number of message IDs is returned.

Authorization. Pointer authorization.

Bit position. The starting bit position, 1-8, for bit strings returned in *HEX format. The least significant bit is 1 and 8 the most significant bit. This field will be initialized to 0 for any other variable type.

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.

Character string length. For output format *CHAR, this value is the length of the returned character string. For output format *HEX, this value is initialized to 0. For fixed character, varying character, and fixed bit variables this field contains the actual length of the data returned for *CHAR and *HEX output formats. For pointers and exception monitors this field is 0.

Comparison string. The specified comparison string.

Comparison string length. The length of the comparison string. This value is 0 if a value is not specified.

Control. Exception monitor control action. The following values may be returned:

Data. The data addressed by the pointer. This field is returned in the corresponding output format for the variable type (data type).

Data error. Whether an error was returned when returning a variable.

Data length. The length of the data addressed by the pointer. This is the same value as in the variable length field in the header.

Data precision. The precision of the data addressed by the pointer. This is the same value as in the variable precision field in the header.

Data retrieved. If an error is encountered while retrieving the data, CPD messages may be returned instead of the variable data. The structure of this parameter is dependent on the object type. The format of the data depends on the variable type field.

Data string length. The string length of the data addressed by the pointer. This is the same value as in the variable string length field in the header.

Data type. The type of data addressed by the pointer. This is the same value as in the variable type field in the header.

Element length. The length of the data element returned. If this field is 0, each element can be a different length and the user must go to the element to get the element length.

Handler type. Exception monitor handler type.

Hexadecimal offset. Hexadecimal offset of the space pointed to by the space or machine space pointer.

Instruction number. The exception handler instruction number for a monitor with an internal handler or X'0' for an external handler.

Job log. Put messages on job log.

Library name. The library containing the object addressed by the pointer, *LIBL, or X'0' for internal monitors.

Message ID. If an error was received with the variable data, this field contains the diagnostic message ID. If no error was received with the variable's data, this field contains blanks.

Message type. Message types being monitored.

More than one message type can be monitored at a time. If the first and third characters are 1's, then escape and status messages are being monitored.

Number of array dimensions. If the variable is an array or an element of an array, this field is the number of array dimensions. Otherwise, this field is initialized to 0.

Number of array elements returned. If the variable is an array, this field is the number of array elements returned. Otherwise, this field is initialized to 0.

Number of message IDs. The number of message identifiers being monitored.

Object addressed by pointer. The fully qualified name of the object addressed by the pointer.

Object type. The Machine Interface (MI) type of the object addressed by the pointer.

Pointer to variable. Pointer to variable, if applicable. For example, a pointer is not returned to a variable of type machine space pointer or for an exception description. For system security reasons a pointer is not returned if the security level is 50 and if the job using the API is servicing and debugging another job.

Program name. External handler program name or X'0' for an internal monitor.

Reserved. An ignored field.

Subscript bounds. The subscript lower bounds and subscript upper bounds for each array dimension. If the variable is not an element of an array, or the dimension is not used, the subscript lower and upper bounds are initialized to 0.

Varying character length. The actual length of the varying character string.

Variable length. The length of the variable value. For bit strings, this value is the number of bits. For packed and zoned variables, this value is the number of digits. For pointers and exception monitors this field is 0. For all other variable types, this value is the number of bytes.

Variable precision. The number of decimal digits or fractional digits for zoned and packed variables. For any other variable type, this field will be initialized to 0.

Variable type. The following are the possible variable types:

Variable value. The value of the variable being retrieved.

The following messages may be returned in this field:

Error Messages