

Contents


      Introduction                               1
      Overview                                   2
      The Script Command Line                    3
      The Script Opcodes and Required Fields     4
	 Change Device Command                   4.1
	 Defines                                 4.2
	 Else                                    4.3
	 Endif                                   4.4
	 Ignore                                  4.5
	 Ifdef/Ifndef                            4.6
	 Iterate Command                         4.7
	 Manual Command                          4.8
	 Separator Command                       4.9
	 Wait Command                            4.10
      Wait Events                                5
      Save Fields                                6
	 Message Processing                      6.1
	 Potential Pitfalls                      6.2
      Sample Scripts                             7
	 Simple Call                             7.1
	 Conference Call Script                  7.2



1. INTRODUCTION

We added a script interpreter to the Telephony Services
Client Simulator when it became obvious that the ability to read and
execute instructions contained in a script file would greatly
facillitate regression testing.   Although originally implemented to
run in exerciser mode, this script interpreter has been exhanced to
run in simulator mode.  It is designed to run in a single user
environment so that input from other activities do not confuse
script operations.  We are including it in the SDK on an "as is"
basis in the hope that it may be of use to others.


2. OVERVIEW

A script file allows a user to execute a file containing a series of
simulator-type commands.  Each command line contains an opcode
indicating the type of action to be executed. Once this action is
executed, the script interpreter halts until an event specified by
the user occurs.  While the script interpreter is waiting for this
"wakeup event", data can be extracted from incoming messages to be
used in subsequent commands.

The script interpreter has been designed to keep the processing
simple.  It is up to the script writer to construct the script so
that it always does what is needed; the script interpreter does not
attempt to decide which data is to be used and what is not.  This
document attempts to provide enough information on how the
interpreter works so that script writing is as straightforward as
possible.

Sample scripts and the resulting output are included throughout this
document.  The two are interwoven with the script command on the right
side of the page and the output at the left margin.  Information 
contained in the output is sometimes abbreviated to make the example
clearer.


3. THE SCRIPT COMMAND LINE

The general format of a script command line is

     opcode  <opcode required fields> <wait> <abort> <save1> <save2>

where each field is separated by white space.  Only the
opcode and the fields necessary for that opcode are required.  The
remaining fields can be defaulted.  However, if the user wishes to
enter a field, all the fields before that field must be entered,
even if the default value is good enough.  Failure to do this
results in curious behavior.

Wait    The wait option tells the script to stop processing until
	a certain event occurs. Most opcodes have a default wait value,
	"WAIT_DEFAULT", so this needs to be set only when the default
	does not do what is needed or if subsequent fields on  the
	command line are used.  In all cases, an abort timer is set to 
	insure that the script does not hang.  If this timer expires,
	the script executes the abort option.

Abort   If a script runs into an error (abort timer expires, a
	csta/acs failure is returned, script error encountered),  it checks
	the  abort option to determine what to do.    The two allowed options
	are "stop" and "continue".  The default is to stop processing.
		
Save1   Once a call is initiated, further requests to control the
	call must use the correct connection ID or call ID.Since this
	information is only known when the call is created, the user must be
	able to save specific information returned in confirmation messages 
	or unsolicited events and to access it in later requests.  The
	interpreter maintains an array of 16 connectionID elements which 
	are identified by the tags ID1,ID2  ... ID16.  By using these 
	tags in this field and the next,"Save2", connection ID data can be 
	saved in one or more of these array elements.
		
Save2   This is also an array tag used to indicate where data is to
	be saved.  See Save1.


Arguments in the command line are case insensitive.  Scripts
may include upper and/or lower case characters in every field.
Users need specify only enough characters in a field to make the
field unique; it is not necessary to spell out every field
identifier.

Scripts may contain comments.  If a "#" sign is placed anywhere on
the command line (outside a text string), all information following
the "#" is treated like a comment.

A field requiring text must be enclosed by quotes, e.g. separator
"Test Case 3.4" .



4. THE SCRIPT OPCODES AND REQUIRED FIELDS

The script interpreter supports most of the CSTA requests supported
by the PBX driver and simulator NLM.  Several additional opcodes
provide both script control functions and the ability to perform
manual functions.  The supported opcodes and the required arguments
are listed below:

		    Table 1:  CSTA FUNCTIONS

     OPCODE         REQUIRED FIELDS          ADDITIONAL FIELDS
***************   ******************       *********************
Answer             ConnectionID              WAIT ABORT SAVE1
Conference         Held_connectionID         WAIT ABORT SAVE1 
		   Active_connectionID
Clear_Call         CallID                    WAIT ABORT SAVE1
Clear_Conn         ConnectionID              WAIT ABORT SAVE1
Hold               ConnectionID              WAIT ABORT SAVE1
Makecall           Calling_deviceID          WAIT ABORT SAVE1 SAVE2
		   Called_deviceID
Monitor_CallVD     DeviceID Call_filter      WAIT ABORT SAVE1
Monitor_Dev        DeviceID Call_filter      WAIT ABORT
Monitor_Stop       DeviceID                  WAIT ABORT
Retrieve           ConnectionID              WAIT ABORT SAVE1
Set_DND            DeviceID                  WAIT ABORT
		   Forward_to_DeviceID
		   On/Off
Set_FWD            DeviceID   On/Off         WAIT ABORT
Set_MWI            DeviceID   On/Off         WAIT ABORT
Transfer           Held_connectionID         WAIT ABORT SAVE1
		   Active_connectionID


		    Table 2:  SIMULATOR FUNCTIONS

    OPCODES        REQUIRED FIELDS          ADDITIONAL FIELDS   
***************   ******************       *********************    
Device_param       DeviceID alert_time       WAIT ABORT
		   connect_time fail_time
		   error_code
Go_offhook         DeviceID                  WAIT ABORT SAVE1 SAVE2
Go_onhook          DeviceID                  WAIT ABORT SAVE1
Inbound_call       Called_deviceID           WAIT ABORT SAVE1 SAVE2
Monitor_ended      Cross_ref  Cause          WAIT ABORT


		    Table 3:  SCRIPT CONTROL FUNCTIONS 
		    
   OPCODES          REQUIRED FIELDS         ADDITIONAL FIELDS                          
***************   ******************       *********************            
Change_device      Index_no  DeviceID
Define             Variable  Expression
Else
Endif
Ifdef              Define_variable
Ifndef             Define_variable
Ignore             On/Off
Iterate            Loop_counter
Manual             Text                      WAIT ABORT SAVE1 SAVE2
Separator          Text
Wait               Wait_interval             WAIT ABORT SAVE1 SAVE2
					    
					    
Table 1  contains CSTA commands which may be used in either
exerciser or simulator mode.  The commands in Table 2
should only be used when running in simulation mode as they are
converted to messages that only the simulator NLM understands.  The
arguments for the opcodes in the first two tables are the same as
the arguments used in the "Send Message" menu.  See chapter 4 of the
DEFINITY System Simulator User's Guide for details.

The required arguments are usually either a device ID which is known 
when writing the script or a connection ID, (call ID, device ID and device type), 
which is only known at run time.  This information must be retrieved from 
a returned message known to contain the information and saved for later use. 
It is up to the user to determine which returned message has the necessary 
information and to take the appropriate steps to save that information.  
This is discussed in more detail in the "Save Fields" section.

Table 3 contains functions that can be used to control script 
processing.  All these commands are available in either mode.  The 
functionality of each is described below.
      
4.1 Change Device Command:

		change_dev   index_no   device_ID

The "change device"  permits the user to replace the device ID within 
a connection ID in an array element(s) with the device ID specified 
on the command line.  More than one array element can be overwritten 
by 'OR'ing the identifiers together.
      
4.2 Defines:

		define   variable   expression

A "define" statement is used to associate a variable name with an 
expression.  This variable name, preceded by a "$", can then be used 
throughout the script wherever the expression would have been used. 
For example, it may be associated with a deviceID in the following way:
      
		define ext1 55851
		define ext2 55852
		define acd2 55042
		define vdn1 55058
		define badext 9999
		define tac_ext1 814605851
		define tac_ext2 814605852
      
Once defined, the variable name may be used in the script as shown
below.  Defines makes it much easier to change the device IDs if the
script is run on a different PBX with different extensions.

		monitor_dev $ext2 0x000 wait_default stop 
		makecall $ext1 $ext2 wait_default stop ID2

Each variable name can be up to 15 characters long and can expand to
a maximum of 63 characters.   A script may contain a maximum of 32
definition statements.

Text strings can include defines instead of the actual device ID.
If the reference is separated from the rest of the text by spaces,
use the normal notation (e.g.  $ext2). If something other than a
space immediately follows or precedes the reference, the reference must 
be set off by braces (e.g. ${ext2}).  In the example below, the $tac_ext1 
field requires braces because it is followed by a period.

     manual "Make Call from $ext2 to ${tac_ext1}." DELIVERED stop 0 ID2

4.3  Else:
See ifdef.                                                          

4.4  Endif:
See Ifdef

4.5  Ignore:
			ignore    on/off

An entire section of the script can be commented out by using the
"ignore" opcode.  Place the command "Ignore on" at the beginning of
the section to be commented out and another command "Ignore off" at
the end of the section.  The script ignores all lines  between the
two statements.

4.6  Ifdef/ifndef
			ifdef  define_variable

A script can be made to execute (or not execute) a section of code
based on the value of a parameter defined in the script.  The value
of this variable cannot change during script processing.  The syntax
is "ifdef" or "ifndef", "else" and "endif" and are similar to "C"
functionality.

      define MAN_MODE  1

      ifdef MAN_MODE
      manual "Call from $ext1 to ${ext2}, hold call on $ext2 and
		Answer incoming call at ${ext2}" ESTABLISHED stop 0 ID4
      else
      makecall $ext1 $ext2 DELIVERED stop 0 ID4
      hold ID2 wait_default stop
      answer ID4 ESTABLISHED stop
      endif
      conference ID2 ID4 wait_default stop ID2
      clear_call ID2 wait_default stop
      
When MAN_MODE is defined, the script prompts the user to perform
the instructions between the "ifdef" and the "else". If the
definition is removed, the script executes the "makecall", "hold"
and "answer" commands - the equivalent of the manual operations.
[The "manual" command is actually on one line; it is broken into two
lines here to fit on the page.]

4.7  Iterate:
		iterate  loop_counter

The iterate command causes the entire script to be executed the
number of times indicated in the "loop counter" field of the command
line.  This command should be the last command in the script;  if it
is placed anywhere else in the script, the script stops executing 
when it reaches the "iterate"command and starts over at the beginning. 
Commands placed after the "iterate" command are not executed.  The 
completion of an iteration is marked by a line on the screen giving 
the iteration count.

When starting a new iteration, the  interpreter closes the script
file, reopens it and  clears all local  variables associated with
the script, including monitors set on a device and the associated
cross reference ID.  As a result, it has no knowledge of monitors
set up or calls placed on prior passes even though these monitors
are still set in the simulator/PBX and the calls are still active.
Resources should be cleaned up prior to the "iterate" command.

4.8  Manual:
		manual   text  WAIT  ABORT  SAVE1  SAVE2

The "manual"  command creates a message box and prints a user
supplied text string inside it.  The user is then prompted to "Hit
'enter' when done".  The text string can be used to give instructions 
about manual operations that must be performed before the script can 
continue.  By striking the enter key when the action is complete, the 
flow of the script is controlled.  Striking the 'cancel' key causes 
the script to execute the abort option.

Users should be careful about the timing of the enter key. If the
key is struck before the manual action has completed, some devices
may not be in their proper state, causing subsequent script commands
to fail.

The text string on the command line may not exceed 99 characters and
must be surrounded by double quotes, ("),  on the command line.

4.9  Separator:
		separator    text

The "separator" command provides a way to divide the output in a
meaningful way.  When this opcode is encountered, a line of stars is
printed, plus the text string, if any, supplied by the user.  The
user supplied text string cannot exceed 99 characters.   The text
string must be enclosed by double quotes, ("), on the command line.

One application of this opcode is separating the results of
different test cases.
	  
     CONFIRM   Clear Connection
     EVENT     Conn Cleared  Call ID: 217  Device ID: 55851 CrossRefID:1
			      Releasing Device:   55851
=>   *****************************  Test Case 2.3 **********************
     REQUEST   Monitor Device 55852
     CONFIRM   Set Monitor    Cross Reference ID: 2
     REQUEST   Make Call Calling Dev: 55851 Called Dev: 814605852
     

4.10  Wait:
	wait   wait_interval  WAIT_CONDITION  ABORT  SAVE1  SAVE2

The "Wait" command allows the user to stop script execution for a
short period of time.  This is can be used to flush the system of 
incoming messages before proceeding with the next script instruction. The
script can be restarted after either a set time interval ("Wait_interval") 
expires or a certain message as specified by the "wait condition" is 
received (see below for more information about "wait" conditions).  The 
script cannot wait on both a timer and an event;  if a timer is set, the 
"wait" condition is ignored.  If the timer interval is zero, the "wait" 
condition is used.  There is no default value for the wait condition.

The timer interval is measured in milliseconds.  If save fields are
indicated, messages that arrive before the timer expires or the wait
message arrives are examined for data.

A "before" and "after" example is given below.  In the "before"
case, the "connection cleared" events arrive after the script
requests a "monitor stop".  Although innocuous in this example, this
behavior can cause problems.  The "after" case waits for 3 seconds
before continuing.  This allows enough time to elapse so the
"connection cleared" events can be processed before the "monitor
stop" is requested.  In the example below the script output is
displayed in abbreviated form on the left.  The script commands are
displayed on the right at the point that the command executes.

BEFORE:
											clear_call  ID2 Wait_def REQUEST
						clear_call  Call ID: 15
   REQUEST  Clear Call     Call ID: 15         
   CONFIRM  Clear Call
   EVENT    Conn Cleared   Call ID: 12  Dev ID: 4441

						monitor_stop 55850
   
   REQUEST Monitor Stop   Cross Ref ID: 1010
   EVENT  Connection Cleared  Call ID: 12  Device ID: 4442 
   EVENT  Connection Cleared  Call ID: 12  Device ID: 4443 
   CONFIRM Monitor Stop
   
AFTER WAIT ADDED: 
						clear_call ID2 Wait_def
   REQUEST  Clear Call     Call ID: 15
   CONFIRM  Clear Call
   EVENT    Conn Cleared  Call ID: 15  Device ID: 4441
   
						wait 3000
							
   EVENT   Conn Cleared  Call ID: 15  Device ID: 4442 
   EVENT   Conn Cleared  Call ID: 15  Device ID: 4443
   
						monitor_stop 55850
   
   REQUEST  Monitor Stop Cross Ref ID: 1013
   CONFIRM  Monitor Stop



5.  WAIT EVENTS:

There are two reasons why actions requested by one command
must complete before processing of the next command begins. First,
information needed in subsequent requests is only available in
confirmation messages and unsolicited events received as a result of
the first action.  Second, there is no guarantee that the call, or
connection on the call, is in the necessary state until the specific
event report is received.

The "wait" field on the command line allows the user to indicate
which incoming message should cause the script interpreter to
continue processing.  Allowed values for the wait event are:

			CALL_CLEARED
			CONFERENCED
			CONFIRMATION
			CONN_CLEARED
			DELIVERED
			DIVERTED
			ESTABLISHED
			FAILED
			HELD            
			NETWORK_REACHED
			NO_WAIT
			QUEUED
			RETRIEVED
			SERVICE_INIT
			TRANSFERRED

Events can be OR'd together if more than one event is acceptable.  A
failure timer (60 seconds) is set each time a command is executed.
If the failure timer expires before the desired message is received,
the script interpreter executes the abort option.

Most opcodes have an associated default event.  If the command line
does not contain a wait argument or if "WAIT_DEFAULT" is specified,
the default value is used.  The default values for each opcode that
uses the wait field are given below:

		Answer          Established | Failed
		Clear_call      Conn_cleared | Call_cleared | Failed
		Clear_conn      Conn_cleared | Call_cleared | Failed
		Conference      Conferenced | Failed
		Go offhook      Service_init | Failed
		Go onhook       Conn_cleared | Call_cleared | Failed
		Hold            Held | Failed
		Inbound call    Delivered | Queued | Network_reached | Failed
		Makecall        Delivered | Queued | Network_reached | Failed 
		Manual          -
		Monitor_callvd  Confirmation
		Monitor_dev     Confirmation
		Monitor_stop    Confirmation
		Retrieve        Retrieved | Failed
		Set_DND         Confirmation
		Set_FWD         Confirmation
		Set_MWI         Confirmation
		Transfe         Transferred | Failed
		Wait            -

Where possible, the default values are unsolicited events. This
assumes that monitors have been set in the script which result in
these events being reported.  There is no checking done by the
script interpreter to guarantee that this is true.

If an event is set as the wait event, the first event of that type
received causes the script to resume processing, even if the event
is the result of an earlier command.  This can cause the script to
work in unexpected ways.

If the devices on the PBX, or in the simulator NLM, are in a known
state, the script writer knows what type of messages to expect in
response to a particular request.  For example, if a destination
device is busy on a call or is not administered as auto answer, a 
makecall request to that device should result in a delivered event 
but not an established event. If the script waits for an established 
event, the failure timer will expire because no established event 
is returned.

If the wait condition is set to NO_WAIT, defined as "0", the script
does not wait at all after executing the opcode;  it proceeds to 
execute the next line in the script.


6.  SAVE FIELDS:

Users must be able to retrieve information from confirmation and event
messages in order to control a call once the call has been initiated.
Commands like "hold" and "clear_conn" require connection IDs as 
arguments, not device IDs.  Save fields allow users to save connection 
ID information returned in messages for subsequent use.  Each "save" 
field identifies a specific entry in an array of connection IDs where 
this type of information can be stored. The array contains 16 elements; 
each element identifier (ID1, ID2, ....) is actually a single bit. 
( ID1 = 1 << 0;  ID2 = 1 <<1,    ...) By logically ORing two identifiers 
together ( ID1 | ID2 ), a save field can be used to save information in 
more than one array element.

The actual "save" implementation evolved as scripts were written for
regression testing.  Two save fields, "Save1" and "Save2", are needed
because the "makecall" request returns two needed pieces of
information: the connection IDs of both the originating and
destination devices.  Other commands, like "diverted" and
"service_initiated", need only one field.  In general, for commands
that use two save fields, "Save1" is used for devices that originate
the call and "Save2" is used for devices that receive the call.  Data
only needs to be saved when it changes.

The save field parameters are the last arguments on the command line.
When the command line is parsed, the values in these fields are saved in  
the "Save1" and "Save2" variables.  The script interpreter extracts 
information from incoming messages only if the appropriate variable, "Save1" 
or "Save2", is non zero. Once a field is zeroed, data in that field is
protected.  Some messages cause a variable to be zeroed once data has been 
extracted; others don't. If the variable is zeroed, no other data can 
overwrite it.  If the variable is not zeroed, subsequent event reports 
can result in overwriting data previously saved.  Again, the implementation 
depends on experience gained in writing scripts.   For example, the 
"delivered" event does not cause "Save2" to be zeroed because another 
"delivered" event may be received if a call goes to a covering device.

Retrieving data from incoming messages is not always as straight forward 
as it may seem.  The script compiler has no way of knowing the type or 
number of messages that may return as a result of executing an opcode 
since this can depend on the number and type of monitors set, the state of 
the calling/called device at the time of the opcode execution and other 
activity at the switch or simulator.  For this reason, responsibility in 
retrieving the desired data resides with the script author.
      
Exerciser mode or "Tracing off" uses only the unsolicited events sent to 
the client simulator.  Simulator mode uses the trace messages of all 
unsolicited messages. In other words, the messages displayed on the client 
simulator screen is what the interpreter uses for "wait" and "save" functions.
      
      
6.1  Message Processing:
      
The algorithm described immediately below represents exactly
what the interpreter does when it receives a message and, hopefully,
can be used to explain why a particular script behaves the way it
does.  The format is a quasi-pseudocode. When retrieving data from
the message, (Section B), the type of message is used to determine
what can be extracted. There is, however, no linkage between the
message that arrives and the opcode of the last command that the
script executed when determining if the script should start
processing again (Section C).  See sample scripts for a description
of some classic problems.

A - Failure Message?:
     If ACS_UNIVERSAL_FAILURE_CONF, SIM_UNIVERSAL_FAILURE_CONF or
	 CSTA_UNIVERSAL_FAILURE_CONF:
	  Execute the abort option. (exit this routine)

B - Data extraction:   if the message is a confirmation, go to B1;
    if it's an event, go to B2:
    
    B1 -If the incoming message is a confirmation message: 
	If a "makecall" confirmation:
		Saves (CSTAMakeCallConfEvent_t *)buf->newCall in the array
			elements indicated by "Save1".
	If a "monitor" confirmation:
		Save (CSTAMonitorConfEvent *)buf>monitorCrossRefID in the
			cross reference table for the current device.
	If a "conference" or "transfer" confirmation:
		Save (CSTAConferenceCallConfEvent_t *)buf >newCall.callID
			in the call ID portion of the connectionID in all 
			array elements indicated in "Save1".
	Break ( Go to section C )
	   
    B2 - If the incoming message is an unsolicited event  and if exerciser 
    mode, does the cross reference ID in the event report correspond to a 
    monitor set by the script?  If not, the event is not used by the script 
    interpreter.  If it is, then:
	If "Delivered" event:
		Save (CSTADeliveredEvent_t *)buf->connection in Save2 array 
		elements. Save2 index is not cleared
	If "Established" event:
		If the current opcode is "answer", "manual" or "wait",saves
		(CSTAEstablishedEvent_t *)buf >establishedConnection in Save1 
		array elements. Save1 index is not cleared.
	If "Diverted" event:
		Saves  (CSTADivertedEvent_t *)buf->connection in Save1 array 
		elements.  Save1 index is cleared.
	If "Network_reached" event:
		Saves  (CSTANetworkReachedEvent_t *)buf>connection in Save2 
		array elements.  Save2 index is cleared.
	If  "Queued" event:
		Saves  (CSTAQueuedEvent_t *)buf->queuedConnection in Save1 
		array elements.  Save1 index is cleared.
	If "Service_initiated" event:
		Saves  (CSTAServiceInitiatedEvent_t *)buf->initiatedConnection 
		in Save1 array elements. Save1 index is cleared.
	If "Held" event:
		If the current opcode is not "HOLD", returns else saves
		(CSTAHeldEvent_t *)buf->heldConnection in Save1 array 
		elements. Save1 index is cleared.
	If "Retrieve" event:
		If the current opcode is not "Retrieve", returns else saves                    
		(CSTARetrievedEvent_t *)buf->retrievedConnection in Save1 
		array elements.  Save1 index is cleared.

C - Wakeup Script?:  is this message one that is supposed to "wakeup" the 
     script?  If so, stop the error timer, initialize opcode parameters and 
     read the next line of the script.

6.2  Potential Pitfalls:

6.2.1. Any confirmation message received is assumed to be for the opcode
just executed.  If the wait event is a confirmation, this message 
causes the script to continue.  Information is not saved as expected. 
Problems may show up immediately or much further down the line.

					  clear_call ID3 Wait_def

REQUEST   Clear Call  Call ID: 275  Device ID: 55851
EVENT     Call Cleared   Call ID: 275   Cross Ref ID:4

					  separator "Case 1.15"
*****************************Case 1.15
					  monitor_dev 55850

REQUEST   Monitor Device  Device ID: 55850
CONFIRM   Clear Call
*****************************Case 1.16

In this example the "clear call" request was waiting for the "call
cleared" event which came in before the confirmation. (see pitfall
#4 for more details) When the confirmation did come in, it satisfied
the wait condition for the "monitor device" command.  Unfortunately,
the cross reference ID which should have been in the monitor device
confirmation message is lost, causing later attempts to stop the
monitor to fail.

6.2.2. Data may be extracted from any unsolicited event that is received
after the opcode is executed and before the wait event causes the
script to continue.  Data from all unsolicited events except the
"Delivered" and "Network_reached" events are saved in the array
elements indicated in "Save1". If this field is zero, no data is
saved.  The default value for "Save1" is zero.  Data from
"Delivered" and "Network_reached" events are saved in the array
elements indicated in "Save2".  If this field is zero, no data is
saved.  The default value for "Save2" is zero.


6.2.3. The order in which messages are returned to the client simulator
are not guaranteed.  Scripts must be written to take this
possibility into account.  Below is an example of how the order of
returned messages differ between two iterations of the same script.
(The script is, obviously, the same in both cases.)

Pass 1:
      REQUEST   Clear Connection    Call ID: 237  Device ID: 55853
      EVENT     Connection Cleared  Call ID: 242  Device ID: 55852  XRef ID:6
      REQUEST   Monitor Stop        Cross Ref ID: 5
      CONFIRM   Clear Connection
      REQUEST   Monitor Stop        Cross Ref ID: 6
      CONFIRM    Monitor Stop
      *****************************Case 2.9 ****************************
      
Pass 2:
      REQUEST   Clear Connection    Call ID: 270 DevID: 55853
      EVENT     Connection Cleared  Call ID: 275  Device ID: 55852 XRef ID:22
      REQUEST   Monitor Stop        Cross Ref ID: 21
      CONFIRM   Monitor Stop
      REQUEST   Monitor Stop        Cross Ref ID: 22
      CONFIRM   Clear Connection
      *****************************Case 2.9 *****************************
      
6.2.4. Conference calls often lead to problems especially if they involve 
ACDs or VDNs. When a call is conferenced by the PBX, the call ID of the 
held call is changed to that of the active call so that all parties
on the call have the same call ID.  If the held device is a monitored
ACD or VDN, a "call cleared" event is sent containing the held call ID.
      
      REQUEST   Conference: Held Call ID: 272 Device ID: 55851
			  Active: Call ID: 275  Device ID: 55851
      CONFIRM   Conference  ID: 275  Device ID: 55851
			  Call ID:  275, Static Device ID 55850
			  Call ID:  275, Static Device ID 55800
			  Call ID:  275, Static Device ID 55851
      EVENT     Conference: Held Call:   Call ID: 272 Dev ID: 55851                 
			  Old Active Call: Call ID: 275  Device ID: 55851
 =>   EVENT Call Cleared   Call ID: 272  Device ID: 0 Cross Ref ID:  3
      REQUEST   Clear Call     Call ID: 275  Device ID: 55851
      EVENT     Call Cleared   Call ID: 275  Device ID: 0 Cross Ref ID:  4
      *****************************Case 1.15
      REQUEST   Monitor Stop   Cross Ref ID: 3
      CONFIRM   Clear Call
      *****************************Case 1.16

      (Data deleted to fit on page)
							 
The simulator NLM generates a completely new call ID when conferencing 
or transferring a call.  Regardless of the mode of the client simulator 
(exerciser/simulator), the new call ID returned in the conference list 
of the "conference" or "transfer" confirmations should be used to 
overwrite the old call IDs in all the saved connection IDs on the call.
Logically "OR" together all the array indices of all the connection
IDs of the parties on the call.

	  makecall 4441 4442 EST stop ID1 ID2
	  hold ID2
	  makecall 4442 4443 EST stop ID3
	  conference ID2 ID3 wait_def stop ID1 | ID2 | ID3

6.2.5. It is most important to remember that there is no explicit
connection between the "Wait" event and the "Save" fields.
Indicating a wait event to be a specific message, e.g. a "Delivered"
event, does not mean that data is retrieved from that, and only
that, "delivered" event. The wait event signals the end of saving
data for that opcode.  See the conferencing example in the Sample 
Scripts section.

6.2.6. All save fields are initialized when a new opcode is executed.
If the expected event for the opcode on a particular line does not
arrive until after the opcode on the following line is executed, the
results are unpredictable.  If there are no save fields indicated on
the following line, no data is retrieved and those array elements
which should have contained the new data, instead contain old data.
If save fields are indicated, the data is saved in these array
elements and may be overwritten by subsequent data or, worse, may
cause the Save1 value to be cleared, leaving incorrect data in the
array elements.


7.  SAMPLE SCRIPTS:


7.1  Simple Call:


The output displayed below is the result of a simple script,
displayed in the second column.  Two device monitors are placed and
a call between the two monitored devices initiated.  When the call
has been established, it is put on hold at the called device.  It is
then retrieved and, finally, the called device hangs up.  The
commands executed by the script interpreter are interleaved with the
actual output to show how the interpreter works.

Notice that the "makecall" request waits for an "established" event
before proceeding.  This is obvious from the output.  The "service
initiated" and two "delivered" events are processed before the
"established" event causes the script processing to continue.
Notice too that there is a second "established" event that is
received after the "hold" request has been made.  Processing
continues after the first message satisfying the wqkeup condition is 
received.  If any data is needed from messages arriving after the 
wakeup message, the script must do something to retrieve it.


****************** SCRIPT HAS STARTED ****************

				       monitor_dev 4441

REQUEST   Monitor Device Device ID: 4441
CONFIRM   Set Monitor    Cross Reference ID: 1006

				       monitor_dev 4442

REQUEST   Monitor Device Device ID: 4442
CONFIRM   Set Monitor    Cross Reference ID: 1007

				       makecall 4441 4442 EST stop ID1 ID2

REQUEST   Make Call Calling: 4441  Called: 4442
CONFIRM   Make Call Call ID: 3  Device ID: 4441
EVENT     Service Init   Call ID: 3  Device ID: 4441
EVENT     Delivered Call ID: 3  Device ID: 4442
EVENT     Delivered Call ID: 3  Device ID: 4442
EVENT     Established    Call ID: 3  Device ID: 4442

				       hold  ID2

REQUEST   Hold Call Call ID: 3  Device ID: 4442
EVENT          Established    Call ID: 3  Device ID: 4442
CONFIRM   Hold Call
EVENT     Held Call ID: 3  Device ID: 4442

				       retrieve ID2

REQUEST   Retrieve Call  Call ID: 3  Device ID: 4442
EVENT     Held Call ID: 3  Device ID: 4442
CONFIRM   Retrieve Call
EVENT     Retrieved Call ID: 3  Device ID: 4442

				       clear_conn ID2

REQUEST   Clear Connection    Call ID: 3  Dev: 4442
EVENT     Retrieved Call ID: 3  Device ID: 4442
CONFIRM   Clear Connection
EVENT     Connection Cleared  Call ID: 3  Device ID: 4442

				       monitor_stop 4441


REQUEST   Monitor Stop   Cross Ref ID: 1006
EVENT     Connection Cleared  Call ID: 3  Device ID: 4442
EVENT     Connection Cleared  Call ID: 3  Device ID: 4441
CONFIRM   Monitor Stop

				       monitor_stop 4442

REQUEST   Monitor Stop   Cross Ref ID: 1007
CONFIRM    Monitor Stop
***************** SCRIPT HAS COMPLETED ***************

If the script used the default condition for the "makecall"
request, a failure would have occurred.  The default for "makecall"
includes "failed", "delivered", "queued" and "network reached".
The script would continue processing when it received the first
"delivered" event and attempt to put the call at the called device
on hold.  The connection ID would be correct, but since the
"Established" event has not been received, the device is still
alerting.  Thus the "hold" would fail because the called device is
in an incorrect state.  To work, the script should wait for the
"established" event.

			      Makecall 4441 4442 WAIT_DEF stop ID1 ID2

REQUEST   Make Call Calling: 4441  Called: 4442
CONFIRM   Make Call Call ID: 4  Device ID: 4441
EVENT          Service Initiated   Call ID: 4  Device ID:4441
EVENT          Delivered Call ID: 4  Device ID: 4442

			      hold ID2

REQUEST   Hold Call Call ID: 4  Device ID: 4442
EVENT     Delivered Call ID: 4  Device ID: 4442
CONFIRM   Failure   INVALID_CONNECTION_ID_FOR_ACTIVE_CALL
**************** SCRIPT HAS BEEN ABORTED ************** 
CONFIRM   Monitor Stop
CONFIRM   Monitor Stop

N. B. :  The monitors  set in the script are stopped when the script
aborts.  This happens only on an abort.  If the script ends
normally, any monitors left active are not stopped.

N. B.: The call that was placed is still active.  If the script is
rerun, it would fail because the resources are busy.


7.2  Conference Call Script:

The following example shows how a conference call can be set up in a
script.

				  monitor_dev 4442

REQUEST   Monitor Device Device ID: 4442
CONFIRM   Set Monitor    Cross Reference ID: 1004

				  makecall 4441 4442 EST stop ID1 ID2

REQUEST   Make Call Calling Device: 4441     Called Device:4442
CONFIRM   Make Call Call ID: 13  Device ID: 4441
EVENT     Delivered Call ID: 13  Device ID: 4442  CrossRef ID:1004
EVENT     Established    Call ID: 13  Device ID: 4442 Cross Ref ID:1004

				  hold ID2

REQUEST   Hold Call Call ID: 13  Device ID: 4442
CONFIRM   Hold Call
EVENT     Held Call ID: 13  Device ID: 4442  Cross Ref ID: 1004

				  makecall 4442 4443 EST stop ID3

REQUEST   Make Call Calling Device: 4442     Called Device:4443
CONFIRM   Make Call Call ID: 14  Device ID: 4442
EVENT     Service Initiated   Call ID: 14  Device ID:4442  XRef ID:1004
EVENT     Delivered Call ID: 14  Device ID: 4443  CrossRef ID:  1004
EVENT     Established    Call ID: 14  Device ID: 4443 Cross Ref ID:  1004

				  conf ID2 ID3 wait_def stop ID1|ID2|ID3

REQUEST   Conference Call:    Held Call: Call ID: 13  DeviceID: 4442
CONFIRM   Conference Call     Call ID: 15  Device ID: 4442 
EVENT     Conference:    Old Held Call:   Call ID: 13 Device ID: 4442

				  clear_call ID2 conn_cl

REQUEST   Clear Call     Call ID: 15
CONFIRM   Clear Call
EVENT`    Connection Cleared  Call ID: 15  Device ID: 4442 XRef ID:1004

The initial "makecall" waits for the "established" event before
proceeding.  The "makecall" confirmation, "delivered" and
"established" events are, therefore, received before the script
resumes.  The "makecall" confirmation message contains the
connection ID of the calling device (4441)and is saved in ID1.  The
connection ID of the called device (4442) is retrieved from the
"delivered" event and saved in ID2.  Neither save index is cleared
but no information is retrieved from the "established" event because
the current opcode, "makecall",  is not the correct type.   When the
script continues, it requests that the call be put on hold at the
device in ID2 (4442).  When the "held" event is received (the
default wait for a "hold" request), a second "makecall" is made from
4442 to 4443.  The connection ID, from the confirmation message, of
the calling device (4442) is saved in the Save1 variable - ID3.
This is overwritten by the connection ID in the "service initiated"
event, but, since the values are the same, the end result is that
ID3 contains the connection ID of the calling device.  The
connection ID of the called device (4443) is not saved because the
Save2 field is 0.  The "conference" request conferences all three
devices together.  The new call ID is saved in all three connection
IDs, ID1, ID2 and ID3.   Note that, in this example, a request to
clear the connection at 4443 would not work because the required
connection ID is not known.
