trap command

The trap BASIC program allows a TCL command (signal handler) to be executed when receiving a specific signal.


Note: For Windows Only: The only functions currently used for Windows implementations are dcd, tmout, and winch.
 trap {pib{}} {[*|signame] {[?|default|command]}}


{pib {}} Allows specifying a signal handler on a pib-by-pib basis. If a is specified, the setting remains in effect, even after the process is exited and reconnected. If no is specified, this defaults to the current pib.
default|command If default is specified, the global trap settings are set back to their defaults. Otherwise, it can be any TCL command, including spaces and options.
signame One of the valid user signal names:
alrm Represents alarm.

When a UNIX SIGALRM is generated, either by a UNIX program called from the D3 process or by the FlashBASIC program calling the %alarm() C function, a signal is sent to the process.

For example: This signal can be used to log the process off after a specified time.

The TCL alarm command generates this signal. The default action is to ignore the signal. Therefore, an explicit trap alrm command must be used.

dcd Represents Data Carrier Detect.

If the DCD protocol is active on one port, a HANGUP signal is generated by the terminal UNIX driver when the DCD signal is dropped by the modem. The default handler logs the process off.

On a network, a more complex program might be necessary to terminate the connection properly and must finish with a disc command.

mirof Represents mirror off.
pwr Represents power off.

When an imminent power failure is detected by UNIX, the kernel sends a SIGPWR signal to all active processes on the system. This signal is relayed to the D3 processes.

Note: Care must be taken to synchronize the default system handler (defined in the inittab) with the D3 handler. This signal might not be generated, depending on the hardware configuration.
tdet Represents tape detach.

When a t-det (u command is issued, the process owner of the tape device receives this signal so that the device can be closed properly. The handler for this signal is a comment.

Note: It must not issue any tape command, including a t-det command.
tdmof Represents tandem off.

When the master process terminates, TANDEM TANDEM ON port.number displays. The slave terminal terminated receives this signal.

tdmon Represents tandem on.

When a process activates the tandem command, you will see the TANDEM STARTED ON port.number message. Both the master and slave terminals receive this signal.

tmout Represents input timeout.

When a process is waiting for keyboard input for more than the amount of time specified by the timeout command. The default behavior is to log the process off.

winch Represents window change.

When a terminal window resize is detected, the signal is executed. The default handler executes the termu program.


The trap command traps a system-generated signal generated by the D3 monitor, or by the UNIX kernel, and executes a TCL statement. Without any argument, the trap command lists the currently global signals.
  • If the pib keyword is specified, the trap command lists the currently used signals for the specified PIB.
  • If no is specified, the trap command lists the currently used signals for the current pib.
  • If the command is not specified, the signal handler is set to null, thus ignoring the signal.
  • If a question mark is used as a command, the signal handler (if any of the specified signal) opens.
? Displays help and the list of user definable signals.
* Specifies all user definable signals.

By default, signal handlers are set for the whole virtual machine. When it is preferable to differentiate the signal handlers depending on the user or account, a FlashBASIC program, a Proc, or an environ script must be provided to execute commands selectively.

The use of the pib keyword allows specifying a signal handler on a pib-by-pib basis. The signal handler is executed by pushing a level. Therefore, you might see some effect on the terminal. For example: You might see the Update processor screen again.

If 15 TCL levels are pushed when the signal occurs, it is not processed. Signals are always preemptive, even on their own signal handler. For a signal handler to be processed correctly, the process receiving the signal must be logged on.

Warning: While executing the signal handler for the DCD loss, and after it has been detected, all terminal output is discarded since there is no device to write to until an input is done. At which point, the D3 process waits for the carrier to come back and restarts normal output. For example: Terminal output is discarded at TCL, FlashBASIC input, and so on.


Example 1

This example lists the current settings:

 Sig    Description       Handler
 -----  ----------------  ------------------------------------------
 tdmon  Start tandem      display TANDEM STARTED
 tdmof  Stop tandem       display TANDEM TERMINATED
 dcd    Modem hangup      off
 mirof  Stop mirror       display MIRROR TERMINATED ON ONE TERM
 alrm   Alarm             un dm,bp, useralarm
 tdet   t-det (U          display Tape detached with (U)
 pwr    Power off         off

Example 2

This example resets all signals to their default:

 trap * default

Example 3

This example disables the signal associated with tandem command on pib 49:

 trap pib 49 tdmon

Example 4

This example sets the tandem on trap to display a message in reverse video:

 trap tdmof display @(-13)tandem entered@(-14)