CASr1 scripting

	local cas_bits = 0x1100
	StackLogTrace( TRACE_LEVEL_2, "Send CAS bits %08X", cas_bits )

This function executes the specified action (in some cases with the specified action-specific arguments).

The action is done asynchronously, meaning that control will immediately return to the script. Events will be received later according to the actions taken.

Upon an event, the script may perform multiple actions (like starting a timer, declaring the call "alerted" and sending CAS bits for example)

Parameters :

• in_Action:
  The action to perform.
  (see Stack Actions for list of available actions)
• ...:
  Variable number of action-specific arguments..
  (see Stack Actions for description of each arguments specific to each action)

Stack actions

ACTION_END_SIGNALING

Indicates either that:

• Application previously requested to terminate the call (with EVENT_APP_END_SIGNALING), in which case this action is used by the script to indicate that signaling is fully idle (local CAS bits set to "idle", remote equipment has acknowledged too with "idle" CAS bits).
• Script wants to terminate the call (after remote equipment set CAS bits to "idle" or after an error in the script). After sending ACTION_END_SIGNALING, the script must wait until EVENT_APP_END_SIGNALING is received, which confirms that application is ready to terminate the call. Only at that moment the script shall set it's CAS bits to "idle" value.

Parameter:

1. The call release cause to report. (See [[#Call_release_causes|Call release causes])

ACTION_SET_CAS_BITS

Changes the CAS bits that we're sending to the remote equipment.

Parameter:

1. CAS bits to set (integer like 0x1111)

ACTION_SEND_WINK

Used to send a "Wink", which is temporary change of the CAS bits for few milliseconds, then back to initial CAS bits value.

EVENT_WINK_COMPLETED will be received by the script once Wink has completed (CAS bits are back to their initial value). Parameters:

1. CAS bits to set during the "Wink" (integer like 0x1111)
2. Duration of the "Wink" (in milliseconds)

ACTION_WAIT_WINK

Used to request a "Wink" detection.

Upon next CAS bits change from remote equipment, the stack will see if the bits match the Wink expected bits.

EVENT_WINK_DETECTED will be reported if CAS bits received from remote equipment change to the expected pattern for a duration within specified range, then go back to original value.

While waiting for a wink, any other CAS bits change not detected as a "Wink" will be reported to the script by EVENT_CAS_BITS_CHANGED

Parameters:

1. Expected CAS bits during the "Wink" (integer like 0x1111)
2. Minimum duration of the "Wink" (in ms)
3. Maximum duration of the "Wink" (in ms)

ACTION_SEND_TONE

Used to send one digit (tone) toward remote equipment. EVENT_TONE_SENT will be received once the tone has been successfully sent. Not normally used in CASR1 standard variants.

Note: This action is not used to send ANI/DNIS (calling/called numbers), it's used to send other tones that may be used within the current CASR1 variant call flow.

Parameter:

1. Digit (tone) to send. See Tones mapping to ASCII characters for details about which ASCII character represents which tone.

ACTION_SEND_ANI

Used to send ANI (calling number) toward remote equipment.

A prefix may be inserted before ANI, and a suffix maybe appended after the ANI.

EVENT_ANI_SENT will be received once transmission of prefix + ANI + suffix is completed.

Parameters:

1. Prefix to send before ANI. Can be empty.
   See Tones mapping to ASCII characters for details about which ASCII character represents which tone.
2. Suffix to send after ANI. Can be empty.
   See Tones mapping to ASCII characters for details about which ASCII character represents which tone.

ACTION_SEND_DNIS

Same as ACTION_SEND_ANI, but for sending DNIS (called number)

ACTION_WAIT_ANI

Used to wait for ANI (calling number) from remote equipment, by detecting tones.

Detection methods for ANI:

1. Prefix/suffix separators indicate the start and/or end of the transmission of ANI.
   If prefix is detected, it's removed from the ANI. If not detected, it does not matter.
   If suffix is detected, it's removed from the ANI, and ANI is immediately reported as complete.
   If suffix is not detected, then another ANI detection method may still trigger end of ANI (inter-digit timeout, or fixed number of digits)
2. Fixed expected number of digits
   With that method, ANI or DNIS is considered complete when the specified number of digits have been received.
3. Inter-digit timeout
   With that method, as soon as there is more than this delay after receiving a digit, the ANI or DNIS is considered complete.

More than one of the methods above can be used (but at least one must be used).

Once ANI has been considered complete by one of the 3 methods above, then EVENT_ANI_RECEIVED is reported to the script.

Parameters:

1. Prefix to expect before ANI. Can be empty. See explanation above.
2. Suffix to expect after ANI. Can be empty. See explanation above.
3. Number of expected digits. Set to 0 to ignore. See explanation above.
4. Inter-digit timeout. Set to 0 to ignore. See explanation above.

ACTION_WAIT_DNIS

Same as ACTION_WAIT_ANI, but for receiving DNIS (called number).

ACTION_SET_ANI

Used by a script that wants to provide the ANI (rather than using ACTION_WAIT_ANI to receive it).

This function is not normally used. But it can be useful in some cases:

• For incoming (backward) calls:
  • Script wants to provide a ANI on a network where no ANI is sent by the remote equipment.
  • Script wants to override the ANI detected (ACTION_WAIT_ANI) by another one chosen by the script.
  • Script wants to collect tones one by one (EVENT_TONE_RECEIVED, and built the ANI from these tones.
• For outgoing (forward) calls:
  • Script wants to override the ANI (calling number) provided by Toolpack when this outgoing call was initialized.

This function must be called before the ANI is used in the signalling process, which means:

• For incoming (backward) calls: before ACTION_REPORT_VALIDATE_CALL.
• For outgoing (forward) calls: before ACTION_SEND_ANI.

Parameter:

1. ANI to set

ACTION_SET_DNIS

Same as ACTION_SET_ANI, but for DNIS (called number).

ACTION_REPORT_SEIZURE

Tell the application that seizure (off-hook) has been detected on a timeslot.

No parameter.

ACTION_REPORT_VALIDATE_CALL

Tell the application that ANI and/or DNIS have been successfully received, and we now have the information required to process this incoming call.

No parameter.

ACTION_REPORT_ACCEPTED

Tell the application that a "forward" call has been accepted by remote equipment, often by detecting a "Wink".

No parameter.

ACTION_REPORT_ALERTED

Tell the application that a "forward" call has been alerted by remote equipment.

On most variants, there is no specific indication from remote side, and this action must be taken upon EVENT_DNIS_SENT.

On other variants, a "Wink" may be awaited before calling this action (variants where there is a second "Wink" after digits are successfully received by remote equipment).

No parameter.

ACTION_REPORT_ANSWERED

Tell the application that a "forward" call has been answered by remote equipment, generally because "off-hook" CAS bits have been received.

No parameter.

ACTION_REPORT_BLOCKED

Tells the application that the script considers the timeslot as "remotely blocked".

This is generally the case when remote side goes "off hook" and does not send digits for a long time, without going back "on hook".

Reporting a timeslot as "remotely blocked" will inform Toolpack that this timeslot cannot be used to make outgoing calls. Toolpack can thus route outgoing calls accordingly.

No parameter.

ACTION_REPORT_UNBLOCKED

Tells the application that the timeslot is no more "remotely blocked", because remote equipment went "on hook" after it was reported "remotely blocked. (in other words, this cancels ACTION_REPORT_BLOCKED)

No parameter.

ACTION_START_TIMER

Starts a timer.

EVENT_TIMEOUT will be posted if the timer expires before ACTION_CANCEL_TIMER is called.

Starting a timer when another timer was already started will cancel previous timer and replace it with new timer.

Parameter:

1. Timer duration in milliseconds.

ACTION_CANCEL_TIMER

Cancels a timer previously started with ACTION_START_TIMER.

No parameter.

Debugging the script

Validating LUA language syntax

The LUA language syntax is automatically validated when saving the script from the Web Portal.

The Web Portal will refuse to save a script that has a LUA language syntax error.

Using log traces

The CAS stack provides the StackLogTrace function that allows the script to print traces through execution.

Traces can be of different levels (more or less verbose). It is recommended to leave traces at various levels through the script so it can be easily debugged "in the field" by simply changing the trace level of the CAS stack while testing a call.

It's also a good practice that the script prints "error" traces to report any error in the log. But be careful not to write error traces in the log for "normal" situations, like calls that fail due to answer timeout for example, as we don't want the logs to be filled out with error traces that correspond to a situation that's actually "normal" on a network.

Viewing traces

All traces printed by the CAS script will be received by the Toolpack tblogtrace application, and written to disk on the host server in the corresponding log file.