Updated January 2016; see History
? tab(-10, AG_ATEDISCONNECT); {flags{,msg}}; chr(127);
AG_ATEDISCONNECT (44) allows the application running on the server to force the ATE client to disconnect. Typically this causes the ATE client window to close.
Parameters
flags (Num)
may contain one or more of the following bits:
|
Value |
Meaning |
|
&h0001 |
Force close-on-disconnect option to ON (no dialog on close) |
|
&h0002 |
Force close-on-disconnect option to OFF (display dlg on close) |
|
&h0004 |
Don't disconnect (just update the close-on-disconnect and msg options) |
msg (string, up to 100 characters)
may contain an optional replacement for the default "Connection reset" message that appears inside a message box when the close-on-disconnect option is not set.
Comments
It is generally considered good style if the application program automatically closes the ATE connection when the user exits or aborts from the main menu (or application login dialog). This eliminates the need for users to learn the various ways of performing independent or manual disconnects (which are usually best avoided altogether). However, there are a few guidelines and points to be aware of when adding this function to your application:
• Although A-Shell/Windows will ignore the command, other emulators will just see a foreign ESC sequence. An easy way to test whether the command is supported is to use the AUI_ENVIRONMENT function and test for the AGF_GUIEXT flag.
• Since the disconnect operation will trigger a SIGHUP signal (same as if the client initiated the disconnection), which in turn will shut down the application, you should perform all your shutdown housecleaning (closing files, etc) before sending the AG_ATEDISCONNECT command.
• For maintenance purposes, it is useful to provide a backdoor around the server-initiated disconnect. (You can base this on the user login, a hidden menu item, a startup switch, etc.)
• To prevent the user from independently or manually disconnecting at an inappropriate time, see Password for Disconnect.
History
2016 January, A-Shell 6.2.1422: The text message option in AG_ATEDISCONNECT is now independent of the flags option. Previous, if the text message was specified, it logged the message to the ashlog file, but effectively forced the flags option to &h0001 (no dialog on close). In other words, the custom message was only being seen in the log, not by the user—which, upon review, seemed just wrong.
2012 September, A-Shell 6.0.1258: Added the two parameters