trap Command

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

Syntax

trap {pib {pib.no}} {[*|signame] {[?|default|command]}}

Parameter(s)

{pib {pib.no}}	Allows specifying a signal handler on a pib-by-pib basis. If a pib.no is specified, the setting remains in effect, even after the process is exited and reconnected. If no pib.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	Stands for 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. This signal can be used to log the process off, for instance, 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	Stands for 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	Stands for mirror off.
	pwr	Stands for 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	Stands for 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.
	winch	Stands for window change. When a terminal window resize is detected, the signal is executed. The default handler executes the termu program.
	tdmof	Stands for tandem off. When the master process terminates, this displays TANDEM TANDEM ON port.number. The slave terminal terminated receives this signal.
	tdmon	Stands for tandem on. When a process activates tandem, this displays TANDEM STARTED ON port.number, both the master and slave terminals receive this signal.
	tmout	Stands for 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.

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, lists the currently used signals for the specified pib, or, if no pib.no is specified, for the current pib.

?	Displays help and the list of user definable signals.
*	Specifies all user definable signals.

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) displays.

By default, signal handlers are set for the whole virtual machine. When it is desirable 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, the user might see some effect on the terminal (for example, the Update Processor screen being displayed again). If 15 TCL levels are pushed when the signal occurs, it is not processed. Signals are always preemptive, even upon 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, after it has been detected, all terminal output is discarded, since there is no device to write to, until an input is done (for example, at TCL, FlashBASIC input, and so on), at which point the D3 process waits for the carrier to come back and restarts normal output.

Example(s)

Lists the current settings.

trap
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

Resets all signals to their default.

trap * default

Disables the signal associated with tandem on pib 49.

trap pib 49 tdmon

Sets the tandem on trap to display a message in reverse video.

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