Hangup

A hangup is a condition by which a device, usually a modem or a network, indicates to the application that communication is no longer possible.

A user terminal can be connected in one of two ways to a device:

  • Direct connection

  • Modem connection

In the first case, the connection is always established. In the second case, however, the connection can be interrupted, due to a modem’s failure to maintain the communication with the remote modem. In this case, the application may need to be made aware of this incident.

Terminal emulation over local or wide area networks is an extension of a modem connection. A network can hang up (close) an open communication. This event is presented to the application as a hangup, or Data Carrier Detect (DCD) loss.

Hangup Signal Handler

The application controls the behavior of the system in case of hangups with the TCL dcd command. When the dcd protocol is off (dcd-off), the application is not notified of a hangup. When the protocol is on (dcd-on), the default behavior is to log off the process.

For UNIX: It is possible to run an application-specific FlashBASIC program or macro to handle the event. This program, usually called a signal handler, is specified by the TCL trap command.

For Windows: Not supported.

While the modem is hung up, all terminal output is discarded, and any input waits for the connection to be re-established, if possible (see the restrictions below, depending on the type of device).

The macro or FlashBASIC program assigned to handle the loss of DCD depends on the type of the device used.

Hangup Signal Handler on a Serial Device

On a serial device, the hangup signal handler can be:

OFF Process is logged off. It stays at logon until the carrier comes back.
EXIT Process is logged off and disconnected from the D3 virtual machine. If the port was marked as respawn, UNIX waits for the carrier to be reestablished before creating the new D3 process. If the D3 process was started manually (that is, from a shell), then UNIX restarts a Shell when the carrier comes back.
Other User provided signal handler can either do an input, which waits until the carrier is reestablished, or just do a stop, in which case the command that was running when the carrier was lost, continues (but the terminal output is discarded), until an input (at TCL or a FlashBASIC input) is required. At this point, the process waits, still logged on, until the carrier is established. See the example below of an application dealing with the possibility of a hangup.

Hangup Signal Handler on a Network

When a process is running on a pseudo terminal, such as the one provided by cloning drivers (rlogin, telnet, and so on), the hang up signal usually means that, not only the connection has been terminated, but also that the pseudo tty (clone) has been destroyed, and possibly allocated to another session. It is therefore impossible to keep the process running on the same pseudo terminal. The choice for the hangup signal handler is limited to:

EXIT Process is logged off and disconnected from the D3 virtual machine. The underlying shell, if it existed, was most likely already killed.
Other User provided signal handler must terminate by running a TCL exit or disc command (such as chain exit). There must be no input, or else an open error is generated.

Example(s)

Hangup Signal Usage

A global flag in a named common is used to indicate a hangup occurred, so that the main application can exit a menu in case of hangup, to abort a command for example. A second global flag display menu is used to tell the signal handler that the user was sitting at a menu when the modem hung up, and that the signal handler should redisplay the menu before terminating.

* Global flag
common /SYSTEM/hangup,display.menu
* Tell we did not hang up
hangup=0
loop
   * Tell we want to redisplay the menu
   display.menu=1
   * Display menu
   call set.menu
   * Get command
   input command
   * Tell we are done with the menu
   display.menu=0
   * Do the desired command
   begin case
   ...
   end case
   * See if hung up during processing
   if hangup then
      * Process some more the hangup
      ...
      * Tell we are done with it
      hangup=0
   end
repeat
Signal Handler

The signal handler sets the global flag hangup in the named common, waits for the carrier to come back. If the user was in the menu, the handler redisplays it after the reconnection.

* Global flag
common /SYSTEM/hangup,display.menu
* Tell we are hungup
hangup=1
* Ignore further hangups
execute "dcd-off"
* Do some application specific cleanup
* (abort current commands, and so on)
...
* IF on a network, the handler MUST exit
* chain "exit" ;* Network only
* Wait for the connection to come back
* An INPUT with a time out of zero ensures
* that the input returns as soon as the
* connection is re-established, without
* requiring that the user actually types in
* something.
input dummy for 0 then null
* Connection is back. See if we need
* to redisplay a menu
if display.menu then
   * We can show the menu again
   call set.menu
   display.menu=0
end
* End of hangup.
* Note we must capture the result to avoid
* disturbing the screen
execute "dcd-on" capturing dummy
* The hangup handler terminates
* The application continues
stop