Reco Register Grammar String

This Reco tool compiles and registers a grammar specified as source text. The recognition subsystem will cache the compiled grammar or re-use an already compiled grammar transparently. The grammar will be active for all subsequent calls to Reco Input until the grammar is deactivated with Reco Unregister Grammar, Reco Unregister All Grammars, or Reco Initialize.

The same grammar source may be registered with multiple IDs, as the IDs simply represent a "moniker" for the grammar. The behavior of registering a different grammar with an ID that already exists depends on the Override Duplicate ID parameter.

When the grammar is registered with Override Duplicate IDs and a grammar with the specified ID already exists, the existing grammar is replaced with the new grammar. Thus, the GrammarID now refers to the new grammar.

Grammars do not have to be explicitly unregistered, as all grammars of a session are automatically unregistered when the session terminates.

Note: Registering the same grammar (source and parameters) multiple times without an explicit ID (i.e. the subsystem synthesizes an ID), will cause a new reference and ID to be generated for each tool invocation.

Inputs

Interaction

Identifier of the interaction.

Grammar Source

Source code text of the grammar given as string.

Grammar Type

Use this optional parameter to define the media type (MIME type) of the grammar referenced by the URL. If not specified, the recognition subsystem deduces the type from the file extension or the HTTP header. However, in general it’s a good idea to specify the MIME type and not rely on the automatic deduction.

This parameter must be empty for built-in grammars.

If a type is specified that is different from the actual data, the tool will take the Invalid Type exit path. The following are the media types of the engine-agnostic grammar formats:

application/srgs	SRGS ABNF
application/srgs+xml	SRGS GrXML
application/x-jsgf	JSpeech

Grammar Mode

Mode of the of referenced grammar. Thus, a grammar with mode "dtmf" is used for DTMF input. The tool will determine the grammar mode from data by default. An error will occur if it is not an engine agnostic grammar.

Note: A grammar cannot apply to more than one mode (Thus, "voice dtmf" is not a valid mode).

Grammar Weight

The bias of this grammar in relation to other grammars, specified as a positive floating-point number. A value greater than 1.0 positively biases the grammar, and a value less than 1.0 negatively biases the grammar. The default value is 1.0. Not all engines support this and it is ignored if not supported.

Registration Mode

Controls when the grammar is sent to the ASR server:

Sync: If the grammar is not already on the ASR server, the grammar is sent to the server and compiled. The tool blocks until the registration succeeded. This most is best for testing as errors will be reported immediately.

Async: If the grammar is not already on the ASR server, the grammar is sent asynchronously and compiled in the background. The tool returns immediately. This most is best to register large grammars whose compilation may take a while and which aren’t immediately used.

Lazy: The grammas is not sent to the ASR server (and no ASR port is allocated if the interaction doesn’t yet have one). The grammar is sent to the ASR server the first time it is used for input. This is the most efficient mode, but grammar compilation errors may not be noticed until the first input is attempted with it.

Grammar ID

ID of the grammar. If not specified, the tool will synthesize one. The grammar IDs must only consist of alphanumeric characters as well as ‘$’ and ‘_’. IDs starting with ‘$’ are reserved for synthesized and other special IDs.

Override Duplicate ID

Specifies behavior if the session already has a grammar with this the specified GrammarID: Leave this box checked if you want pre-existing grammars to be overwritten by new grammars using the same ID. I.e., if a grammar with the specified ID has already been registered for this session, the old grammar will be un-registered and replaced with the new grammar.

Clear this box if you do not want older grammars to be overwritten. If this box is unchecked, then if a grammar with the specified ID has already been registered for this session, the tool will exit via the Failure exit path with error code "error.com.inin.grammar.id.duplicate".

Outputs

New Grammar ID

Grammar ID of the grammar. If a Grammar ID is specified as an Input, the same value is returned. If none is specified, this parameter returns a synthesized ID.

Error Code

If the registration fails, this output parameter contains an error code in the form of a VoiceXML event. This will be an empty string if no error occurred.

Error Text

If the registration fails, this output parameter will contain a simple textual description of what went wrong (e.g. reason for compilation error).

Exit Paths

Success

This path is taken if the grammar by the grammar text has been successfully compiled and activated.

Failure 

This path is taken if some other error occurred.