Flow control instructions

Flow control instructions determine the order in which the instructions are executed. Each instruction is listed with a brief description. An example of a script using these instructions follows the descriptions.

• case(type.src,type.src[,subroutine_label]goto_label)
case(type.src,type.src[,subroutine_label ()]goto_label)
case(type.src,type.src[,subroutine_label(type.src)]goto_label)
case(type.src,type.src[,subroutine_label](type.src,type.src)goto_label)

  The case instruction provides a conditional subroutine call that compares two source values. If the source values are equal, the subroutine is called, and on return, execution continues at the goto_label address. If they are not equal, the statement does nothing. If the subroutine_label is a negative number, no subroutine call is made and execution continued at the goto_label. If the goto_label is negative, execution continues with the next instruction.

  Subroutine calls invoked in a case statement behave like other subroutine calls (that is, with arguments allowed and register values saved on the stack).

• event(event_type [, subroutine_label ])
event(event_type [, type.offset ])

  The event instruction allows script execution to continue after certain events occur, such as when the caller hangs up or the script detects another external event. 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 /att/msgipc/tsm_dip.h header file.

  If valid arguments are passed, the event instruction returns an integer offset in 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 which 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. 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 described briefly below. See TAS script instructions, for more information about the event instruction and event types.

  • EHANGUP specifies a hangup event. This event is triggered when dial tone, no loop current, disconnect, or glare conditions are detected on the channel.
  • EDIALTONE and ESTUTTERDT specify a dial tone event. 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.
  • ESOFTDISC specifies a soft disconnect event. This event is triggered by sending a SOFT_DISC message to TSM from a DIP. 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

  • EDIPINT specifies a DIP interrupt event. This event may be triggered by sending a DIP_INT message from TSM to a DIP. 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

  • ETTREC specifies a touch-tone received event. This event can be used to allow a dbase, sleep, tflush, 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 (that is, 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 ttclear
    r.3	Instruction interrupted: t - tflush, s - sleep, d - dbase, i - tic

    If no event subroutine is set for ETTREC, the instructions are not interrupted by touch tones.

  • EANSSUP specifies an answer supervision event. This event is triggered when answer supervision (rather than speech energy detection) is detected as available for a telephony interface. This includes T1, E1, and PRI. It also includes LSE1 or LST1 when the system is connected to a DEFINITY ECS or compatible switch and the DTMF Feedback to VRU feature is available.
• exec(ctype.script [, type.data, type.nbytes ][, exitval ])

  The exec instruction allows a script to execute another script or IRAPI application.

  The ctype.script argument is the name of the script to be executed. The type.data and type.nbytes optional arguments are used to pass a block of data to the new application. The type.data argument specifies the location of the data and the type.nbytes argument specifies the size, in bytes, of that data. If type.data is a register or immediate type, type.nbytes is ignored and a size of an integer (4 bytes) is assumed. These two arguments work like the last two arguments of the dbase instruction.

  The exitval argument is an optional exit value used when the parent script is terminated before the new child script is run. It is passed to a DIP specified by the dipterm instruction in the same way as the argument to the quit instruction and may be specified without using either type.data or type.nbytes. If no exitval is given, -1 is used by default. See TAS script instructions, for more information on the exec instruction. See also: subprog.

• execu(ctype.script [, type.data, type.nbytes ][, exitval ])

  The execu instruction has the same format and functionality as exec. Using execu instead of exec, however, causes the new script to inherit, the user data space of the parent script intact. Essentially, this feature allows a script to pass all user data to the new script. For this to be useful, however, the new script must have its data defined in the same way as the parent script (that is, structures, variables, etc., must be defined for the same locations). The data definition of the new script is used to overlay the actual data of the parent script.

• goto(label)

  The goto instruction is an unconditional jump to the instruction indicated by the label.

• ibrl(type.dst, type.src, label)

  The ibrl instruction, which means increment and branch if less, determines if another pass should be made through a loop. The ibrl instruction normally is placed at the end of the loop. The destination value is incremented by one and then compared to the source value. If the destination is less than the source value, a jump to the labeled instruction is executed and the loop is repeated. If the destination is greater than or equal to the source, the next instruction is executed.

• jmp(type.src rel_op type.src, label)

  The jmp instruction is a conditional jump to the labeled instruction. The rel_op argument compares the values of the two source operands. If the condition is true, a jump to the labeled instruction is executed. If false, the statement does nothing. The rel_op has six C-style operators:

  If rel_op is . . .	Then . . .
  ==	Equal
  !=	Not equal
  <	Less than
  <=	Less than or equal to
  >	Greater than
  <=	Greater than or equal to

• label:

  A label definition assigns a label to a program segment. It is not the same as label() (described below), which is a subroutine call.

• label ([ type.src ] [, type.src ]])

  The label instruction is used to call a subroutine found at the address indicated by the label: of the segment. A return address and the values in all registers except r.0 are saved on a subroutine stack. An optional first argument is stored in r.3 and an optional second argument is stored in r.2 for use by the called subroutine. Otherwise, the registers are left unchanged.

• nap(type.src)

  The nap instruction makes the script do nothing for the specified number of centiseconds (hundredths of a second).

• nwitime(type.src)

  The nwitime (next wait instruction time) instruction sets the maximum amount of time the script waits for the completion of the next instance of the following wait-causing instructions. The type.src argument specifies the number of seconds to wait.

  • dbase
  • phreserve
  • sr_talkoff
  • tic
  • tstop
• quit([ exitval ])

  The quit instruction terminates the script voluntarily. An optional parameter is passed to a DIP specified in a dipterm instruction. This exitval is also returned to the parent script in register 1 (r.1) if the script is executed with the subprog() instruction.

• rts()

  The rts instruction is the mechanism for returning from a subroutine call. The saved values for all script registers except r.0 are restored.

• scrinst([ctype.script])

  The scrinst instruction enables an application script to find out how many instances of a script are running currently on the system. Based on the value returned by this instruction, the script may choose to prohibit execution of another instance of the script (using the exec instruction) or the script may quit if it is performing a check on itself and has exceeded the limit.

  The ctype.script optional argument is the script or service name. If no script name is given, the script executing the instruction is assumed. This instruction sets the value of r.0 to the number of instances of the given script at the time the instruction is invoked.

  There are several possible uses of scrinst based on the ways in which a script may be started:

  Incoming call	It is suggested that the method of limiting the number of scripts started with an incoming call be left as it is. That is, do not assign a service to a number of channels greater than the desired limit. If the number of channels assigned to a script exceeds the limit, a script still may check the instance count as its first task and quit before answering the call if the instances exceed the limit.
  exec	The exec script instruction is the primary means by which an instance limit may be exceeded. Therefore, any application script concerned about running too many instances of another script should use scrinst for that script before using exec. In this case, it is important to avoid a wait condition in the interval between scrinst and exec. This could cause other scripts running simultaneously that are performing the same test to receive identical results from scrinst before any of them perform the exec instruction. Use tflush before scrinst to play any speech that is queued. If tflush is not used, the exec instruction causes the speech to play and the script waits for the play to complete before executing the exec instruction.
  Soft seizure	Scripts started by a soft seizure request from a DIP may use scrinst to check themselves against an instance limit as their first task, similar to the way scrinst may be used if the script is started by an incoming call. If the script determines that it cannot continue, it may signal the DIP that started it by using the dipterm instruction and calling quit with a specific value that the DIP may check.

• sleep(type.src)

  The sleep instruction makes the script do nothing for the number of seconds specified by the argument.

• subprog(ctype.appname [, type.data, type.nbytes ])

  The subprog instruction allows a script to execute another TAS script or IRAPI application as a subprogram, and then return to the parent script with data from the subprogram.

  The ctype.appname argument is the name of the script to be executed. The type.data and type.nbytes optional arguments are used to pass a block of data to the new application. The type.data argument specifies the location of the data and the type.nbytes argument specifies the size, in bytes, of that data. If type.data is a register or immediate type, type.nbytes is ignored and a size of an integer (4 bytes) is assumed. These two arguments work like the last two arguments of the dbase instruction.

  The subprog instruction returns values in both register 0 (r.0) and register 1 (r.1). r.0 is 0 if subprog is successful. It contains a negative value to indicate failure. If successful, subprog also returns in r.1 whatever value is passed to the quit instruction by a called TSM script application, or whatever value is passed to irReturn by a called IRAPI application. See TAS script instructions, for more information on the subprog instruction. See also: exec.

© 2006 Avaya Inc. All Rights Reserved.