Programming Scripting FAQ

Most of the events, methods, and properties supported by the Microsoft Agent control are exposed only at run time. Consult Programming the Microsoft Agent Control for further information.

Some tags include quoted strings. For some programming languages, such as Microsoft Visual Basic and Visual Basic Scripting Edition, you may have to use two quote marks to designate the tag's parameter or concatenate a double-quote character as part of the string. The latter is shown in this Visual Basic example:

Agent1.Characters("Genie").Speak "This is \map=" + chr(34) + "Spoken text" _ + chr(34) + "=" + chr(34) + "Balloon text" + chr(34) + "\."

For C, C++, and Java programming, precede backslashes and double quotes with a backslash. For example:

BSTR bszSpeak = SysAllocString(L"This is \\map=\"Spoken text\"=\"Balloon text\"\\");

pCharacter->Speak(bszSpeak, ......);

This could be caused by one of the following problems:

• Your programming language doesn't fully support ActiveX controls. Check your documentation to ensure that it supports the ActiveX interface and events for ActiveX objects.
• On a scripted webpage, another control has failed to install or load. Check to ensure that all other controls are installed and loading properly without Microsoft Agent.
• On a scripted webpage with frames, you have the <OBJECT> tag for the Microsoft Agent control on one page, and the events scripted on another page. Events are sent only to the page that hosts the control.

Check to see if the other controls are correctly installed. If another ActiveX control fails to correctly register itself, the Microsoft Agent control may receive its events.

Microsoft Agent should be supportable from any language that supports the ActiveX interface. It includes code samples for Visual Basic, VBScript, JScript, C/C++, and Java.

Yes, but currently the only way to do this is using the <SCRIPT LANGUAGE="JScript" FOR="*object*" EVENT="event()"> syntax. Although this syntax is supported for Microsoft Internet Explorer, other browsers do not support it, so you may want to avoid using JScript for this part of your page's script.

Yes, provided that the engine supports the Microsoft Speech API (SAPI) 4.0 interfaces required by Microsoft Agent. Check with the engine supplier. For complete details on the SAPI interfaces required by Microsoft Agent, see Speech Engine Support Requirements.

Typically, the problem can be corrected by refreshing the page. As a general practice, it is best to specify the Microsoft Agent Control <OBJECT> tag first, then the Lernout & Hauspie TruVoice engine, then the Command and Control speech recognition engine.

When you play an animation, the animation services continue to display its last frame until another animation is called. Therefore, you should play another animation after calling MoveTo. If you defined a Return animation for the Moving state animation, the server will play it first.

This occurs if the character has been compiled using a speech engine's default pitch property; that is, the pitch was not changed when the character was built.

To set the TTSModeID property, you must have Speech.dll installed. This is typically a part of the speech engine's installation code. You may also install this by installing the Speech object control panel , available from the Microsoft Agent Downloads page.

The Microsoft Agent control does not unload a character object (release the reference) when its associated character file fails to load. If you want to retry loading the character, you must explicitly call Unload before you call Load the second time. If you attempt this from a webpage script, you also need to precede the Unload call with an On Error Resume Next statement, or the Unload call will also fail. (Note that JScript has no On Error Resume Next statement.)

However, you may not need to include code to immediately retry loading a character when the file fails to load. Microsoft Internet Explorer and the Microsoft Agent server component automatically attempt to retry several times, so the chances that your retry will result in a successful load are remote. A better strategy is to wait (set a timer) a few seconds before you retry.

You can install Agent from the Microsoft website by including its CLSID in an HTML Object tag. However, if you want to include and install Agent from your own application installation program or from your own server, you must download the Microsoft Agent self-installing cabinet file, by downloading it from the Downloads page. When downloading, choose the browser's Save rather than Run option. Whenever this file is run, it automatically will install Microsoft Agent on the target machine. Therefore you can specify the file in your installation script.

Do not attempt to install Microsoft Agent by copying its various .DLLs and attempting to register it yourself. Attempting to install Agent by any other means then executing its self-installing cabinet file is not supported.

The target system must also include recent versions of MSVCRT.DLL (VC++ runtime), REGSVR32.EXE (registration tool included with Microsoft VC++), and COM. The best way to ensure that the correct versions are installed is to require that Microsoft Internet Explorer 3.02 or later is installed. However, you can also license these runtime requirements. (For the latest version of COM, access the DCOM update from the Microsoft website.)

Microsoft Agent 2.0 will not install on Microsoft Windows 2000 since this version of the operating system already includes Agent.

While you can create your own installation program using Visual Basic (VB) code you can't use the Visual Basic Setup Wizard to do this. To install Agent from VB, you can use Shell command, specifying the Microsoft Agent self-installing cabinet file.

Microsoft Agent 2.0 does not install on Windows 2000 because it is already included as a part of the operating system.

This may result when the character has been using TTS for spoken output, then changes to use a WAV file. Text was not supplied in the first parameter of the Speak method.

To avoid the crash, include a space character in the first parameter of the Speak method, even if you have no text output.

This usually happens when you have Agent applications such as Microsoft Office 2000 open when you install the Agent language component. Close all applications and try again. If the problem persists, restart your computer and you should be able to set the language ID now.

This is a known issue. You can work around this by using the map tag. For example to display "A & B" in the character's word balloon, use "A \map="and"="&&"\ B" in the Speak statement.

There are two possible causes:

If you change the TTS Mode ID of the default character and then allow the user to change the default character through ShowDefaultCharacterProperties, AgentSvr will crash.

This problem has been fixed in the Windows 2000 and Windows XP operating systems. To avoid the crash on other platforms, you should either not allow the user to change the default character after you change the default character's TTS Mode ID, or do not use the default character in your application or webpage.

If your application does not use Microsoft-supplied Agent characters, make sure that your customized character uses a palette with a full palette of 256 colors. For more information see the Designing Characters for Microsoft Agent document.

This is a known issue with IE 5. There was a change in how the browser handles a certain event, which causes the HTML script to begin running before AgentSvr is started. In order to make your page work with all versions of the browser, you need to add this line to your script:

AgentControl.Connected = True

which explicitly creates a connection to the AgentSvr. Note that you only need to do this if your page loads Agent from multiple frames.

A previous version of the Agent core component cabinet file MSAGENT.exe, when executed on Windows 2000 (and Windows XP), will block installation and display an inaccurate error message that Agent is not compatible with the version of the operating system you are running. In fact, Microsoft Agent 2.0 core components are included as part of Windows 2000 (and Windows XP), and are already installed by default through Windows setup.

In this version, the check is removed and the installation file will not display the aforementioned error message under Windows 2000 (or Windows XP). Note that this is the only change to the installation file, and there are no code changes to the Agent core components themselves. Therefore, you are not affected by this update if you already have Agent 2.0 installed, or if your website uses an object tag to trigger automatic downloads of the Agent core components from the Microsoft Object Store.

If you include the Agent core component installation file with your application, or if you post the installation file on your server, you may want to download this update. To do so, click here and select the "Save this program to disk" option. You must have a valid and current Agent distribution license for these circumstances.

Alternately, you can also work around this problem by using the silent option when installing the previous version of the MSAGENT.exe installation file. The shell command is:

MSAGENT.exe /q:a

The same applies to the Agent language components that were originally released in October 1998. There was a check that would prevent the Arabic, French, German, Hebrew, Italian, Japanese, Korean, Simplified Chinese, Spanish, and Traditional Chinese language components from installing under Windows 2000 (and Windows XP). The newer versions of these installation files, along with the additional 19 languages added in March 2000, do not contain this check and will install successfully on Windows 2000 (and Windows XP).

This is a known issue for characters created with a palette of less than 256 colors. Issues with these characters include the transparency color showing in the background, transparent balloon text, transparent balloon border, or transparent balloon background. Note that such characters may cause your applications to crash when loaded in the Agent character picker dialog or the Microsoft Office Assistant gallery. Your customized characters must use a full palette with 256 colors. You can use the sample palette provided for Office Assistant characters as a starting point with a full 256 color palette.

First make sure you have all the necessary components installed—Agent core components, the SAPI runtime binaries, and a SAPI4 compliant British English TTS engine like the TTS3000 British English engine, available for download on the Agent Downloads page. If your character is still not using the British English TTS engine, it's likely you also have an American English TTS engine installed. Since both British and American English share the same primary language (English) and American English is the default, Agent will pick the first available American English TTS engine as returned by SAPI. To use a British English TTS engine, use the character's TTSModeID property instead. For example, the TTSModeID for the TTS3000 British English male voice is {227A0E41-A92A-11d1-B17B-0020AFED142E}. In Microsoft Visual Basic you can use this engine by setting Merlin's TTSModeID as follows:

AgentControl.Characters("Merlin").TTSModeID = {227A0E41-A92A-11d1-B17B-0020AFED142E}

This is a known problem. On Windows 95, Windows 98, and Windows Me operating systems, the character's volume does not change but will remain at the previously set level. On Windows NT 4.0, Windows 2000 and Windows XP platforms, this will cause AgentSvr to crash, even when a TTS engine is not installed. Since the range of the character's volume, from 0 (silence) to 65535 (maximum volume), is large and the difference between successive levels is hardly discernable, the easy workaround is to set the volume to 1 instead of 0 when you want the character's voice to be inaudible.

Make sure a simple speaking animation is assigned to the Speaking State. For example, you can use a single frame consisting of the character's neutral position with mouth overlays.