general.hangup Definition/General

general.hangup

Command general.hangup Definition/General
Applicable release versions: AP 6.1
Category General (155)
Description is a condition by which a device, usually a modem or a network, indicates to the application that communication is no longer possible.

Overview :

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 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 are 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. On Unix implementations, it is possible to run an application specific Pick/BASIC program, or macro to handle the event. This program, usually called a signal handler, is specified by the TCL "trap" command.
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 Pick/BASIC program assigned to handle the loss of DCD depends on the type of the device used.


Hangup Signal Handler on Serial Device :

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

"OFF" The process is logged off. It stays at logon until the carrier comes back.

"EXIT" The process is logged off and disconnected from the Pick virtual machine. If the port was marked as 'respawn', Unix will wait for the carrier to be reestablished before creating the new Pick process. If the Pick process was started manually (i.e., from a shell), then Unix will restart a Shell when the carrier comes back.

Other The user provided signal handler can either do an INPUT, which waits until the carrier is reestablished, or just do a stop, in which case whatever command was running while the carrier was lost, just continues (but the terminal output is discarded), until an input (at TCL or a Pick/BASIC INPUT) is required. At this point, the process will wait, still logged on, until the carrier is established. See below an example of 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, etc...), 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" The process is logged off and disconnected from the Pick virtual machine. The underlying shell, if it existed, was most likely already killed.

Other The user provided signal handler MUST terminate by doing an TCL 'exit' or 'disc' command (such as 'chain 'exit'). There must be NO input, else this will generate an open error.
Syntax
Options
Example
Hangup Signal Usage example :

A global flag in a named common is used to indicate a hangup occurred, so that 
the main application can exit of 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, etc...)
...

* 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 will return 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
Purpose
Related tcl.dcd
tcl.dcd-on
tcl.dcd-off
tcl.trap