Reviewed and revised December 2023
tab(-10, AG_HOLDKBD); opcode; chr(127); Tab(-10,x) Syntax Notes
AG_HOLDKBD (36) puts the ATE client into "keyboard hold" (aka "local keyboard") mode. For example:
tab(-10, AG_HOLDKBD); "2"; chr(127);
Parameters
opcode
2 or 4
Response
None
Opcode 2
opcode 2 locks ATE into the local/hold mode, where it will stay until explicitly released.
Once locked into this mode, no keyboard characters will be transmitted to the server except indirectly via ATE command/response packets. Normally, the server and ATE determine between themselves when ATE should act like a dumb terminal (transmitting all keyboard characters) and when it should act like a client GUI workstation (sending keyboard input to local edit controls only), based on contextual clues.
The lock feature is mainly intended for AMOS and other non-A-Shell servers which cannot detect or communicate such clues. Locking the ATE client into local keyboard mode eliminates problems with type ahead being sent inappropriately to the server, or worse, interrupting/confusing commands sent between the server and client via the keyboard channel.
To remove the lock, use:
? tab(-10,AG_RELEASEKBD);"2";chr(127);
Or, you can also clear it via the Settings menu to clear the Local Kbd Mode checkmark.
Note that once set, the local lock remains set until cleared by one of the above methods, even at the dot prompt. So while the feature may be thus turned on globally in a startup command file, you must be sure to turn it off before exiting to the dot or before performing any non-GUI input operations, including subroutines GET, TINKEY, ACCEPT, the INPUT statement, etc.
Opcode 4
opcode 4 activates a timer in ATE that after 15 seconds of no activity from host (when not otherwise waiting on user actions, such as within INFLD, XTREE, XTEXT, EVENTWAIT, etc.), a message box is displayed warning the user that communication with host appears to be broken, and giving the option to continue waiting or send a cancel (^C).
This can help mitigate a situation where the host application has crashed, leaving ATE in a state which appears to the user to be hung but actually isn't. To activate/deactivate the feature:
? tab(-10,AG_HOLDKBD);"4";chr(127); ! activate
? tab(-10,AG_RELEASEKBD);"4";chr(127); ! deactivate
Timeout monitor is only active when the ATE workstation is in "hold-kbd mode"—i.e. when the AG_HOLDKBD "2" option has been activated or when currently processing an ATE command from the host.
There are situations where it may be normal for ATE to be left waiting for something from the host for longer than 15 seconds. For example, if the host uses XCALL HOSTEX to launch a child task, it could be left waiting indefinitely for a response, leaving ATE in a waiting state. It is the responsibility of the host application to identify such situations and disable the appropriate AG_HOLDKBD mode(s).
When opcode 4 is set, ATE will display a "waiting for <host address>..." message on the session status line (if visible), when appropriate. Even if not visible, the cursor will be change to the wait cursor while in this state. The idea is to give the user some indication of what is going on when output is delayed due be network, application, or server problems, and is somewhat analogous to the similar message displayed by most browsers when waiting on a server response.
The display is updated every one second by adding a dot, and after fifteen seconds, a modeless dialog appears that says:
Server/network not responding. Click CANCEL to send abort request. Or just wait to see if it recovers. [Cancel]
Clicking Cancel sends a Ctrl+C to the host, which may or may not be useful, depending on the situation and how the application responds to Ctrl+C.
As soon as any characters arrive from the server, the dialog is removed and the cursor is restored the normal arrow or I-beam.
History
2015 January, A-Shell 6.1.1399: Add opcode 4.
2013 October, A-Shell 6.1.1364: When the keyboard is locked into local mode with argument "2", ^C no longer clears the local hold. It is simply queued up as would be the case for other keyboard characters, either to be consumed by a local input operation or eventually forwarded to the host when the hold is removed.
2013 May, A-Shell 6.1.1352: Add option "2" to lock ATE into local keyboard mode.
