|
|
|
|
|
The event instruction causes a subroutine call when defined events occur.
Synopsis
event(event_type [,subroutine_label])
event(event_type [,type.offset])
Description
The event script instruction causes a jump to the subroutine_label given when events defined by the event_type argument occur. The event types are defined in the header file /att/msgipc/tsm_dip.h.
If valid arguments are passed, the event instruction returns an integer offset in register 0 (r.0). This offset is the value of the previous subroutine_label (if any) used for the event. It may be saved and used later as the type.offset argument to the event instruction to reset the subroutine_label back to its previous value. (This is useful for external script functions that need to handle events and want to restore their disposition to whatever the calling script had set before returning.)
If event_type is not valid or type.offset is larger than the text space of the script, a value of -3 is returned by the event instruction.
A negative value for type.offset may be used to set no subroutine label for an event, causing the default action to be taken when the event occurs (see below). If no subroutine_label or offset is given, the event instruction returns in r.0 the value of the subroutine_label currently being used (or -1 if none) without changing the disposition for the event.
The event types are as follows:
This event is triggered when dial tone, no loop current, disconnect, or glare conditions are detected on the channel. The register value passed to the event subroutine is EHANGUP for r.0. If no event subroutine is set for this event, the script exits as if the quit instruction were used.
These are special cases of the EHANGUP event. Normally, EHANGUP is triggered when dial tone or stutter dial tone is detected (and the script is not expecting dial tone). EDIALTONE and ESTUTTERDT are used to treat dial tone detection separately from EHANGUP. If both EHANGUP and EDIALTONE or ESTUTTERDT are set with the event instruction to call different interrupt routines, EDIALTONE or ESTUTTERDT must be set following EHANGUP.
The register value passed to the event subroutine is EDIALTONE for r.0. If no event subroutine is set for this event, the script exits as if the quit instruction is used.
This event is triggered by sending a SOFT_DISC message to TSM from a DIP. This message is acknowledged with a SOFT_DPASS message before the event subroutine is called. Note that if the channel specified by the SOFT_DISC message is idle, a SOFT_DFAIL message is returned.
If an event subroutine is set, it receives the following values when the event occurs :
r.0 |
Event type (ESOFTDISC) |
r.1 |
Value from arg[1] of SOFT_DISC message |
r.2 |
Value from arg[2] of SOFT_DISC message |
r.3 |
Number of the DIP that sent the SOFT_DISC message |
If no event subroutine is set for this event, the script exits as if the quit instruction were used.
This event can be triggered by sending a DIP_INT message from a DIP to TSM. The DIP_INT message is not acknowledged.
If an event subroutine is set, it receives the following values when the event occurs:
r.0 |
Event type (EDIPINT) |
r.1 |
Value from arg[1] of DIP_INT message |
r.2 |
Value from arg[2] of DIP_INT message |
r.3 |
Number of the DIP that sent the DIP_INT message |
If no event subroutine is set for EDIPINT, TSM ignores the DIP_INT message and the script continues to run.
This event can be used to allow a dbase, sleep, tflush, talkresume or tic instruction to be interrupted if a touch tone is received while they are being executed. Note: The tflush instruction is only interrupted if its first argument is 1 (talkoff is disabled).
If an event subroutine is set, it receives the following values when the event occurs:
r.0 |
Event type (ETTREC) |
r.1 |
Touch-tone character that caused the interrupt |
r.2 |
Number of touch tones received since last getinput or ttclear |
r.3 |
Instruction interrupted (t - tflush or talkresume, s - sleep, d - dbase, i - tic) |
If no event subroutine is set for ETTREC, the instructions are not interrupted by touch tones.
This event is triggered when answer supervision is detected for an E1, T1, or PRI channel.
The register value passed to the event subroutine is EANSSUP for r.0. If no event subroutine is set for this event, the event is not triggered and the script continues to run.
This event is triggered when a resource that has been explicitly allocated with the resource_alloc() instruction is removed due to a maintenance process.
If an event subroutine is set, it receives the following values when an event occurs:
r.0 |
Event type (ERESOURCE) |
r.1 |
Removed resource capability value (see resource_alloc) |
r.2 |
Removed resource implementation value (see resource_alloc) |
If no event subroutine is set for ERESOURCE, the script is not notified of removal of explicitly allocated resources.
Note:
If an explicitly allocated resource is removed, the system still attempts to dynamically allocate the resource for the script on an as needed basis (as if the resource_alloc() instruction were never used).
The DIP number stored in r.3 for ESOFTDISC and EDIPINT events is the same value used by the dbase and dipterm instructions. It can be used directly by those instructions in the event subroutines, if desired.
Return from an event subroutine is handled the same for all events. If the event routine causes a wait condition, any previous wait condition is forgotten. If the event routine sets r.0 to a negative value before returning (with the rts instruction), any previous wait condition is aborted. The wait causing instruction then returns immediately with r.0 still set to that negative value. In most cases, this simulates a failure condition for the interrupted instruction. If r.0 is not negative when the event routine returns, the script continues to wait for the expected condition before it continues. When the event routine returns, all registers except r.0 are restored to the values they had before the event. Events of different types may be nested. A new event is ignored if an event of the same type is being handled already. The EDIALTONE event also is ignored while EHANGUP is being handled.
Example 1
The following example shows when a hangup is detected, the script calls the subroutine hangup which records the time in event data space and exits.
#define ATD_TIME 24
MAIN:
tfile("list.atd_mgmt")
event(EHANGUP, hangup)
...
hangup:
load(ev.ATD_TIME, time.0) /*Record time attendant becomes free*/
...
quit()
Example 2
The following example shows that when a touch tone is detected during the tflush(1) instruction, the script stops the play only if the touch-tone digit is #. Note that any received digits are not removed from the script touch-tone buffer unless a getinput or ttclear instruction is done.
MAIN: ...
event(ETTREC, L_tkoff)
talk("something")
tflush(1)
/* tflush will return a -5 in r.0 if talkoff (# only) */
...
event(ETTREC, -1) /* reset event */
...
L_tkoff
jmp(r.3 !='t', L_notkoff) /* not tflush */
jmp(r.1 !='#', L_notkoff) /* not # digit */
tstop()/* stop play */
load(r.0, -5) /* abort tflush() */
rts()
L_notkoff:
load(r.0, 0) /* continue instruction wait */
rts()
