# Variables Details

- Related to Recognition
  - Grammar Objects
  - SWI_literalTimings
  - Other SWI_* variables
- Related to Transfers/Calls
  - signalvar Objects
  - Instance ID Variables
  - Conference ID Variables

Grammar Objects

A "grammar object" is an ECMAScript object with the following properties:

`grammartype`, set to one of the following values:

- `universals` - Hot key grammar
- `builtin` - Built-in grammar
- `external` - External grammar
- `inline` - Inline grammar
- `choice` - Implicit grammar using `<menu>` and `<choice>`
- `option` - Implicit grammar using `<field>` and `<option>`
- `link_builtin` - Built-in grammar with `<link>` as its parent
- `link_external` - External grammar with `<link>` as its parent
- `link_inline` - Inline grammar with `<link>` as its parent

`rulename`, set with the following rules:

- If `grammartype` is "`universals`", `rulename` will be "`hotkey`"
- If `grammartype` is "`builtin`" or "`link_builtin`", `rulename` will be the builtin type (ie. "`boolean`", "`date`", etc.)
- If `grammartype` is "`inline`", "`link_inline`", "`external`", or "`link_external`", `rulename` will be the root attribute (if specified) of the VoiceXML grammar tag that references the grammar (not the root attribute of the grammar tag in the actual XML grammar). Note that this will generally be `undefined`
- If `grammartype` is "`choice`" and the `<menu>`'s `id` attribute is defined, `rulename` will be the id; otherwise, `rulename` will be an internally generated rule id
- If `grammartype` is "`option`", `rulename` will be the `<field>`'s `name` attribute

`grammaruri`, set with the following rules:

- If `grammartype` is "`universals`", "`choice`", "`option`", "`inline`", or "`link_inline`", `grammaruri` will be `undefined`
- If `grammartype` is "`builtin`" or "`link_builtin`", `grammaruri` will be "`builtin:grammar/builtin_type`"
- If `grammartype` is "`external`" or "`link_external`", `grammaruri` will be the full path of the grammar file

`pageuri`, set to the URI (with full path) of the VoiceXML page that references the grammar

`linenumber`, set to the line number in the VoiceXML page where the grammar reference starts. This is set with the following rules:

- If `grammartype` is "`universals`", `linenumber` will be `undefined`
- If `grammartype` is "`option`", `linenumber` will be the line number of the `<field>` tag
- If `grammartype` is "`choice`", `linenumber` will be the line number of the `<menu>` tag

(special OSR variable, available with SpeechWorks ASR only)

If you want to access this variable, you must set:

    <property name="com.voicegenie.fieldobject" value="true"/>*
    <property name="com.voicegenie.asr.get_swi_literaltimings" value="true"/>

*Note: `com.voicegenie.fieldobject` is true by default.

Then, after each utterance, the special OSR variable SWI_literalTimings can be accessed through the variable `application.lastresult$.interpretation.SWI_literalTimings`. For example:

    <log>
       SWI_literalTimings:
       <value expr="application.lastresult$.interpretation.SWI_literalTimings"/>
    </log>

The SWI_literalTimings contains information about the beginning and ending times of the words recognized. It returns the literal string with time markings for each word. For example:

    <alignment type="word" unit_msecs="1">
      <word start="720" end="1000">one</word>
      <word start="1050" end="1240">eight</word>
      <word start="1240" end="1540">four</word>
      <word start="1540" end="1880">five</word>
      <word start="1880" end="2280">nine</word>
    </alignment>

Since there may be silence between words, the end time of a word often does not equal the start time of the next word.

Limitations

1. IMPORTANT: The SWI_literalTimings are only available if the grammar sets at least one slot. If there are no slots set, the SWI_literalTimings will be undefined, and the field/recognition variables may be set to unexpected values.
2. Only the first n-best result has the variable returned.
3. If the SWI_literalTimings string (in which any character {`<` `>` `:` `|` `+` `#` `\"` `\n` `\t`} is escaped in a format of `0xHH`, where `HH` is its hex representation) is longer than 2048 bytes, the value of `application.lastresult$.interpretation.SWI_literalTimings` will be "string_is_too_long".
4. SWI_literalTimings is not available for built-in grammars such as boolean, currency, date, digits, number, phone, and time.

Other SWI_* variables

SWI_grammarName

This is used internally, and is not accessible from the VoiceXML page.

SWI_literal

The value of this variable is accessible from the VoiceXML page through `application.lastresult$.utterance`, where the nbest results are separated by ":".

SWI_meaning

There are a couple cases, depending on what the grammar returns:

1. Root rule of the grammar returns no slots. For example:

    <grammar xml:lang="en-US" version="1.0" root="ROOT">
       <rule id="ROOT">
          <item>january</item>
       </rule>
    </grammar>

In this case, the SWI_meaning is the same as the SWI_literal. It can be accessed as above, or through the field name variable* (only if the grammar is field-level).

2. Root rule of the grammar explicitly sets the SWI_meaning. For example:

    <grammar xml:lang="en-US" version="1.0" root="ROOT">
       <rule id="ROOT">
          <item tag="SWI_meaning='JAN';">january</item>
       </rule>
    </grammar>

In this case, the SWI_meaning is used as the recognition value. It can only be accessed through the field name variable* (only if the grammar is field-level).

3. SWI_meaning is not explicitly set, but other tag content is specified. For example:

    <grammar xml:lang="en-US" version="1.0" root="ROOT">
       <rule id="ROOT">
          <item tag="slotname='JAN';">january</item>
       </rule>
    </grammar>

In this case, OSR sets SWI_meaning by concatenating all keys/values (other than SWI_*) defined in the root rule, and this is returned as the recognition result. This result will be parsed to fill the field and lastresult variables*, but no single variable contains the original SWI_meaning, as such. The `application.lastresult$.interpretation` variable has similar contents (slots and values), but they have been reformatted.

SWI_rawScore

This variable cannot be returned to the interpreter to make accessible from the VoiceXML page, due to the result format.

signalvar Objects

The `<transfer>` and `<call>` tags each support the `signalvar` attribute, which can be used to send information with the call request. The `signalvar` attribute must be set to an ECMAScript object containing properties as documented below. The properties allow the developer to specify details related to the following aspects:

- Outbound Call Control
  - Line Selection Settings
  - Call Analysis Settings
  - Other VoiceGenie Settings
- Call Setup
  - Call Setup Settings for Other Protocols
  - Additional Call Setup Settings

Example 1. Using `signalvar` in a `<transfer>`:

    <form>
       <var name="callvars" expr="new Object()"/>
       <block>
          <assign name="callvars.ani" expr="17817781500"/>
          <assign name="callvars.pri" expr="0"/>
          <assign name="callvars.numbertype" expr="1"/>
          <assign name="callvars.numberingplan" expr="2"/>
       </block>
       <transfer signalvar="callvars" .../>
    </form>

Example 2. Using `signalvar` in a `<call>`:

    <form>
       <block>
          <var name="callvars" expr="new Object()"/>
          <assign name="callvars.ani" expr="17817781500"/>
          <assign name="callvars.pri" expr="0"/>
          <assign name="callvars.numbertype" expr="1"/>
          <assign name="callvars.numberingplan" expr="2"/>
          <call signalvar="callvars" .../>
       </block>
    </form>

Note: When setting a numeric literal (like the ANIs in the two above examples), please note that the JavaScript engine will treat numeric literals as octal numbers if they start with 0. To prevent this, enclose your ANI in single quotes, so that it is treated as a string instead. See complete details. In the examples above, the ANIs don't start with 0, so the same digits will be passed whether or not single quotes are used.

Call Set up

IMPORTANT NOTE: Even if one of the following call setup properties is assigned a valid value and sent, using `signalvar`, in a supported call environment, it still may not have any effect on the called party. To have an effect on the called party, a property/feature must also (a) be supported by the switch or remote party, and (b) be supported by the service provider.

The call setup details include the following sections:

- Call Setup Settings for Other Protocols
- Additional Call Setup Settings

Call Setup Settings for Other Protocols

Most of the following properties are supported with ISDN; some are supported with other protocols. In any case, they will be set in the call setup message and sent to the switch/remote party.

Name | Purpose | Supported Environments
ani | Calling party number (Automatic Number Identification); used to set the telephone number of the caller. Note: This variable must be written in capital letters - i.e., "ANI" rather than "ani". | SIP
numberingplan | Numbering Plan of called party; used to set the numbering plan. See session.connection.numberplan for possible values. | VoiceGenie
numbertype | Number Type of called party; used to set the number type. See session.connection.ntype for possible values. | VoiceGenie
pri | Presentation Restriction Indicator; used to set the calling party's presentation restriction. See session.connection.pri for possible values. | VoiceGenie
rdnis | Redirect DNIS (Dialed Number Information Service) to be set in Diversion headers; used to set the telephone number from which a call diversion or transfer was invoked. | SIP
rreason | Redirect Reason to be set in Diversion headers; used to set the reason the call was redirected to this server. See session.connection.rreason for possible values. | SIP
uuidata | User-to-User Information; used to set a string of limited length containing User-to-User Information (UUI) data to be sent, over the PSTN, to an application on the far-end. For example, if a `<transfer>`, with uuidata set in the `signalvar`, is used to call another VoiceXML application (and if the network configuration supports the transmission of UUI data), then the UUI data string will be available in the session variable `session.telephone.uui`/`session.connection.aai` in the called application. Note that in any case, the called party must have a device that is capable of retrieving the sent data, if the intent is to have them access this string. | VoiceGenie

Additional Call Setup Settings

Note that the `signalvar` object can contain arbitrarily many other properties, beyond those documented above. Whenever the `signalvar` contains a property that can be set in the call setup message (according to the protocol of the platform's call environment), VoiceGenie will include the property and its corresponding value in the call setup message. Any properties that are neither documented above nor part of the protocol in use will be ignored; they will not be sent to the switch/remote party, and they will not have any effect on the called party.

Instance ID Variables

Interpreter instance IDs have the same value as the session ID for the corresponding session. Specifically, `session.com.voicegenie.instance.myself` has the same value as `session.com.voicegenie.telephone.primarychan`.

Here's an example of the instance ID/session ID format:

       000B0006-1004A6BE-0001

Note that this format no longer provides the platform IP address. The _VGGetInfo() function can be used instead, to get the platform IP address.