Retrieve Prompt Override (QPTRTVPO) API

The Retrieve Prompt Override (QPTRTVPO) API calls the prompt override program for a specified command and returns the prompt override command string from the prompt override program.

Authorities and Locks

Command

*USE

Prompt override program

*EXECUTE

Library

*EXECUTE

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The variable that is to receive the information requested. The minimum size of this area is 8 bytes. You can specify the size of this area to be smaller than the format requested as long as you specify the length parameter correctly. The API will not attempt to return more data than the receiver can hold.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable. If this value is larger than the actual size of the receiver variable, the results may not be predictable. The minimum length is 8 bytes.

Receiver variable format name

INPUT; CHAR(8)

The format of the receiver variable. RTVP0100 is the only valid value. For more information, see RTVP0100 Format.

Command string

INPUT; CHAR(*)

The command string containing the command name and the key parameter values. The command name may be library-qualified. The command string should be in the format in which it would be entered on a command line. Values must be specified for all key parameters.

Length of command string

INPUT; BINARY(4)

The length of the command string. Valid valids are between 1 and 32 702. The length can include trailing blanks but must not include trailing null characters.

Error code

I/O; CHAR(*)

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

RTVP0100 Format

The RTVP0100 format includes information on the contents of the receiver variable. The following table shows how this information is organized. For detailed descriptions of the fields in the list, see Field Descriptions.

Field Descriptions

Bytes available. The length of all data available for the requested format. All available data is returned if enough space is provided.

Bytes returned. The length of all data actually returned. If the receiver variable is not large enough to hold the data, no other data is returned and this value is less than the bytes available.

Length of prompt override command string. The length of the prompt override command string returned by the API. If the prompt override program completed normally, but did not return a command string, this will be 0. If the prompt override program ended in error, this will be -1.

Offset to prompt override command string. Offset to the first byte of the prompt override command string.

Prompt override command string. The command string returned by the prompt override program. The command string will not include the command name, the key parameters, or any other parameters not specified by the prompt override program. If the receiver is not large enough to hold the entire command string, the command string will not be returned, and the Bytes available field will have the size of the receiver value required for the command string.

Prompt override program library name. The name of the library in which the prompt override program was found.

Prompt override program name. The name of the prompt override program that was called to supply the prompt override command string.

Usage Notes

While this API is threadsafe, it should not be used to call a prompt override program that is not threadsafe in a multithreaded job.

Error Messages