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.

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 Appendix C of the CL Reference (Abridged) book.

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 Appendix C of the CL Reference (Abridged) book.

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.

Offset		Type	Field
Dec	Hex
0	0	BINARY(4)	Bytes returned
4	4	BINARY(4)	Bytes available
8	8	BINARY(4)	Variable type
12	C	BINARY(4)	Data error
16	10	POINTER	Pointer to variable
32	20	BINARY(4)	Bit position
36	24	BINARY(4)	Variable length
40	28	BINARY(4)	Variable precision
44	2C	BINARY(4)	Number of array dimensions
48	30	BINARY(4)	Number of array elements returned
52	34	ARRAY(15) of BINARY(4)	Subscript bounds
172	AC	BINARY(4)	Element length
176	B0	BINARY(4)	Character string length
180	B4	CHAR(64)	Reserved
244	F4	CHAR(*)	Data retrieved

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:

X'00'

Default

X'01'

Off

X'02'

Resignal

X'04'

Defer

X'05'

Handle

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.

0

No errors were returned with the variable data.

1

One or more errors were returned with the variable data.

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.

'00'X

External handler

'01'X

Call internal handler

'02'X

Branch point handler

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.

0

No

1

Yes

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.

100

Escape

010

Notify

001

Status

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:

1

Binary numeric

2

Floating point

3

Zoned decimal

4

Packed decimal

5

Fixed character

6

Varying character

7

Fixed bit

8

Unsigned binary

9

Space pointer

10

Data pointer

11

Instruction definition list

12

System pointer

13

Machine space pointer

14

Exception description

Variable value. The value of the variable being retrieved. The following messages may be returned in this field:

CPD1901

Variable contains invalid decimal data.

CPD1902

Pointer to be displayed not set to any address.

CPD1903

Floating-point value displayed is not exact.

CPD1904

Object not found for system pointer with initial value.

CPD1905

Variable not found for data pointer with initial value.

CPD1906

Variable to be displayed contained in deleted object.

CPD1907

Variable refers to object with freed storage.

CPD1908

Space addressing error for variable.

CPD1909

Pointer alignment error. Pointer not on 16-byte boundary.

CPD1910

High-level language (HLL) pointer invalid.

CPD1911

START plus LEN values exceed length of string.

CPD1913

Space addressing error for variable.

CPD1914

Pointer addresses a deleted object.

Error Messages

CPF1902 E

No default program exists.

CPF1903 E

Program &1 not in debug mode.

CPF1905 E

Starting position parameter is not valid.

CPF1906 E

Command is not valid. No programs in debug mode.

CPF1915 E

Length parameter is not valid.

CPF1919 E

Recursion level parameter is not valid.

CPF1927 E

Output format name not valid.

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.

CPF24B4 E

Severe error while addressing parameter list.

CPF3C19 E

Error occurred with receiver variable specified.

CPF3C24 E

Length of the receiver variable is not valid.

CPF7133 E

Variable or basing pointer name missing.

CPF9549 E

Error addressing API parameter.

CPF9872 E

Program or service program &1 in library &2 ended. Reason code &3.