Action return values

Overview

Many x3270 actions, especially those designed for scripting and screen scraping, return a value. These values can be displayed at the x3270> prompt, or inspected by scripts.

Other actions are intended for interactive use. They produce only side-effects and do not return a value.

Returned value

When an action returns a value, it can be seen in the following ways:

• In b3270, the run-result indication has an optional text attribute. If the action succeeds, this is the return value. If it fails, it is an error message. An empty text attribute indicates an empty return value. If there is no text attribute at all, then the action does not return a value.
• In the s3270 protocol, the return value (or error message), if any, precedes the next prompt.

• At the x3270> prompt, the output from a successful action is displayed in the window's default foreground color.

• The HTTP server returns the result of an action (or an error message) in the body of the reply.

Success or failure

Actions succeed or fail. When an action fails, if it is part of a macro (a sequence of actions to be executed in sequence), the macro is terminated and fails. If the action was executed as part of another action, such as the Source() action, the parent action will terminate and fail.

The success or failure of an action can be seen in the following ways:

• In b3270, the run-result indication has a success attribute, which is true if the action succeeds and false if it fails.

• In the s3270 protocol, the prompt ends with ok for an action that succeeds, and with error for one that fails.

• At the x3270> prompt, the output from an action that fails is displayed in red.

• When an action fails, the HTTP server returns a 400 (Bad request) error.

Version history

In x3270 4.1, the Set() action (when asked to return a single setting) and the Ascii(), Ascii1(), Ebcdic(), Ebcdic1() and NvtText() actions were changed to return an empty value when appropriate. In previous releases, Set() would return a single space character, and the other actions would return no value.