Action return values

Description
Many x3270 actions, especially those designed for scripting and screen scraping, return a value. These values can be displayed at the x3270&gt; 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&gt; 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 also 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&gt; 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.