


	Version 1.45 © 2003 by CapeSoft Software (Pty) Ltd www.capesoft.com Updated 20 October, 2003


for more agents see www.msagentring.org	E-Clips Animations

Contents
		General Information
		Introduction [Suggested Reading]
		Copyright and License
		Distribution [Very Important]
		Where can you get it
		How to get Technical Support
		Acknowledgements
		Getting Started - some basics
		Installation Instructions [Suggested Reading]
		Quick jump start [Recommended Reading]
		Some More Detail
		Using the Agent Templates
		Using the Special Agent DLL windows
		Examples
		Features
		Using 3rd Party Agents
		Agent Voice Changing
		Useful General Tips and Info [Recommended Reading]
		Support
		Error Messages
		Frequently Asked Questions [Latest FAQs immediately after the FAQ index]
		Technical Documentation
		Microsoft Agent Documentation
		Removing Special Agent from your Program
		Version History [Suggested Reading for existing users]

Introduction

Special Agent provides an excellent way of using a Microsoft Agent to learn and play back sequences, which are useful for training and help. This will not only reduce the programmer's training time, but also will reduce technical support and provide all sorts of other features like demos, etc.

Special Agent integrates the Microsoft Agent OCX into your program. You can teach a sequence or series of sequences, which can be played back by the user at relevant points in the program. The Microsoft Agent can be used in these sequences to highlight certain points and explain important details. Special Agent also takes control of your mouse while running sequences to show which buttons must be clicked, fields entered, etc.

Note: Special Agent can only be used in 32-bit applications and in Clarion 5 or later.

Installation Instructions

Installing Special Agent, with ABC support, is a 2 step process:

1.	Run the supplied installation program. (You may have already done this, to get this far).
2.	The Special Agent template will be automatically loaded when you run the install program.

Note:
There are some example applications which you can find in the clarion5\3rdParty\examples\agent (or c55\3rdParty\examples\agent) directory, which will demonstrate some of the features of Special Agent. The applications with a 'leg' suffix use legacy the legacy templates and those with 'abc' suffix use the ABC class templates. Compile these applications and check out some of the sequences as well.

You will also need to install the OCX components to enable the agents (more info).

Quick jump start

For those of you who hate reading manuals - this section is especially for you. Unfortunately there are always the few things that you absolutely have to know before you get started in order to at least get the ball rolling. This is only for single EXE apps - for multi-DLL applications you'll need to read up a bit more on the Global Extension template.

1. What you need to do to your application

1.1	You need to add the Special Agent Global extension template to your application. To do this:

1.1.1	Click the 'Global' button on the Application tree window.
1.1.2	Click on the 'Extensions' button on the 'Global Properties' window.
1.1.3	Click on the 'Insert' button on the 'Extension and Control Templates' window.
1.1.4	Select the 'Activate_Agent' template from the list of extension templates and click on the 'Select' button.
1.1.5	Back at the 'Extension and Control Templates' window the should appear the template with its details on the right.

1.2	You'll need to set-up the 'How Do I?' menu on the frame. To do this:

1.2.1	Select the frame procedure on which to the menu options will be placed.
1.2.2	Click on the 'Properties' button.
1.2.3	Click on the 'Extensions' button to edit the local extension.
1.2.4	On the Main Details tab, select a menu from the drop down list. This must be a valid menu or the application will not compile. The menu must also have a valid Clarion 'Use variable'. The agent menu 'How Do I?' will be placed onto this menu at run time. (Using the ?Help menu is normally the best)

1.3	You'll need to set your application to 32-bit mode. To do this:

1.3.1	Click on the 'Project' button on the Application tree window.
1.3.2	Highlight the 'Project: Generator' item in the Project Tree and click on the 'Properties' button.
1.3.3	In the 'Global Options' window that appears, select 'Windows - 32-bit' in the 'Target OS' drop-down list.
1.3.4	Click the 'OK' button (x2) to save the properties.

1.4	Now you can compile and run your application.

2. A quick guide in creating sequences

2.1	Once your application is running, press CTRL-F12 to bring up the Sequence Window. The list box should be blank (since you have not created a sequence yet). To create a sequence:

2.1.1	Click on the Learn button (book icon) on the Sequence Window
2.1.2	The 'Adding a Sequence Record' window appears with the 'Name' prompt highlighted. Enter a unique sequence name here.
2.1.3	Press the ENTER key or click the 'OK' button.
2.1.4	The 'Learn Sequence' window appears indicating that you are now in learn-mode. Any steps you perform will now be added to the current sequence. It's a good idea to start your sequence with an 'Open Agent' step (click lamp icon button) and finish it with a 'Close Agent' step (click crossed-out lamp icon button).
2.1.5	To quite out of learn mode, click on the 'No-learn' button (crossed-out book icon), which will bring you back to the 'Sequence Window'

2.2

To run the sequence that you have just created, click on the 'Run' button (VCR Play icon). Each step that has been learnt while in learn mode will now be performed. If you want to stop the sequence before it is completed, double-click on the agent and select the 'Stop' item from the pop-up menu that appears.

What You Need to Distribute to your Users

As the Microsoft Agent is a Microsoft product, you will have to acquire the necessary free distribution license from Microsoft in order to distribute the Microsoft Agent with your program. You can get the all the Agent documents, programs, etc from the Microsoft website: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msagent/intro_9ywk.asp and the license details are also there: http://msdn.microsoft.com/library/default.asp?url=/library/en-us/msagent/lic_7h66.asp

You may, however, use the Microsoft Agent distributed with Special Agent for your own personal use as this is licensed.

When you distribute your Special Agent enabled application, if it's compiled in 'stand-alone' mode (i.e. it requires the use of DLLs) then you will need to ship the following DLLs with your application:

DLLs required
	Clarion Version	DLL required
	Clarion 5	C5MSAX.DLL C5OLEX.DLL
	Clarion 5.5	C55MSAX.DLL C55OLEX.DLL

You will also need to distribute all the normal TopSpeed DLLs that you would ship with your standard Clarion application.

TopSpeed DLLs required
	File Name	Description
	'Agent.tps' file	The file containing the sequence information
	'Gestures.tps' file	The file containing the Agent, Gestures, Languages (optional) and Voices (optional) information.
	The Agent OCX files	These are the install-sets for the Microsoft Agents. This includes the Agent OCX (MsAgent.exe), at least one speech-engine (like tv_enua.exe) and at least one character (<Character>.exe). If you require voice changing, then you need to install the Microsoft Speech Control Panel (spchcpl.exe) on each PC where voice changing is required.

Important Note: Don't create a sub-directory called 'Agent.tps' (or whatever you've named your sequences file) in the directory from which you run your program as this will split up your Agent.tps file into 5 files. The same goes for 'Gestures.tps' (or whatever you've named your gestures file).

Template Guide

Note: There is no support (at present) for report and process templates, so the Special Agent code will be omitted from these template types.

Important Note: When quitting from a window you must use the ProcedureReturn or the ThisWindow.Kill procedure so that the necessary settings of Special Agent are updated.

The Agent Global Extension Template

The Agent Local Extension Template

Running a Sequence from a button (Control Template)

Running a Specific Agent Sequence (code template)

Using an Agent to say a brief message (code template)

Changing the Special Agent Language (code template)

Get the available agents (code template)

Get the Agent Error details (code template)

Disable Special Agent form the entire application at runtime

The 'Setup Agent's popup menu' code template

1. The Agent Global Extension:

The first step (once your application is open) is to add the Global Extension. To do this:

1.1	Click the 'Global' button on the Application tree window.
1.2	Click on the 'Extensions' button on the 'Global Properties' window.
1.3	Click on the 'Insert' button on the 'Extension and Control Templates' window.
1.4	Select the 'Activate_Agent' template from the list of extension templates and click on the 'Select' button.
1.5	Back at the 'Extension and Control Templates' window there should appear the template with its details on the right.
1.6	Check the 'No Agent' check box if you don’t want to generate any Special Agent code. This is useful if your app doesn't compile and you want to exclude all agent source when compiling.
1.7	The 'This is part of a Multi-DLL App' check box is used to indicate that the Agent data is exported from another DLL.
1.8	The 'Export Agent defined in this DLL' check box (which is hidden unless the application is a DLL) should be checked if the Agent data must be exported to other applications.
1.9	If this is an EXE change to the 'File Details' tab (EXE Only), or else continue with step 1.21.
1.10	The default file name for the sequence file is 'Agent.tps'. You can change this by entering another file (and a path if you require a set path) or a variable (by omitting the quotes) into the field provided. If the file name field is left blank, the file name will automatically default to 'Agent.tps'.
1.11	Check the 'Use this file for the Character Gestures' if you want to store the characters and their gesture sets in this file. (see What Files to Use for some suggestions on file usage)
1.12	If you left the 'Use this file for the Character Gestures' unchecked then you may enter a file name and path here (don't use quotes if you want to enter a variable name). If left blank, then a "Gestures.tps" file will be used to store the characters and their gesture sets.
1.13	If you are wanting to omit learning some events (like size/move) you can enter a file setting for this file in the 'File to store excluded events'. This file is only used for learning purposes, and will not prevent events from being sent that are already in the sequence. This is purely a time saver to prevent general unwanted events from being entered into the sequence. You may want to make one Excluded events file for all your Special Agent programs and keep this in one place, or you may decide to use one for this application. (see 'Excluded Events' in the 'Setup' on excluding events)
1.14	Change to the 'Translation' tab. (EXE Only)
1.15	Check the 'Use Special Agent's Translator' checkbox if you require the Special Agent windows and messages to appear in a language other than English. (see Translating the Special Agent DLL for more details on translating)
1.16	The Default language file is the file that the translator is set to use at program start-up. You may change this file using the 'Call_MsALanguage' code template.
1.17	The Position options are used to determine where the translation files are stored. You can either select the EXE directory or specify another directory. If the translation files are not there when the program is run, a new translation file will be made.
1.18	The 'All Messages into Translation File on Start-up' is useful when creating a translation file. If this is checked, then on program start-up, Special Agent will ensure that all the messages it uses are in the translation file. The ones that it does not find are written into the translation file there and then. If this is left unchecked, then it will only check the messages in the translation file as the occur individually.
1.19	The 'Restrict Menus to One Language' is useful if you have a sequence file containing sequences of more than one language. This will restrict the sequences displayed in the 'How Do I?' menu and the sequence popup menus to the setting below. If unchecked, then all the language settings of the sequences in the sequence file will be ignored.
1.20	The 'Selected Language' is the language that you select to limit the sequences to. This language must match a language in the Special Agent language file, otherwise the language setting will be ignored. Note: If you leave this field empty, the Special Agent will maintain the Sequence Selection Limiter changes in the agent ini file. Update this setting to use the changes made in the Change the Language item from the Sequence window. (see International Support for more details)
1.21	Change to the 'Other' Tab.
1.22	The 'Force IMM attribute on windows' is used to ensure that all windows have the IMM attribute. If a windows does not have the IMM attribute, then the agent.DLL is not updated with the new positions of the window when it is moved/sized. If you require that a window does not have the IMM attribute, check this off and ensure that all your other windows have the IMM attribute checked on. You will need to ensure that when that window's dimensions or position is changed that you use the function ds_SendPosition to inform the agent.DLL of the changes.
1.23	The default Hot key to bring up the Sequence window is 'Ctrl-F12'. If you require a different Hot key, you can select one here. (EXE/Data DLL only)
1.24	The 'Keep Agent open after running sequence' check box will keep the agent open when the sequence is finished running. This is useful if you want the agent continuously open, e.g. running random sequences now and then. (EXE/Data DLL only)
1.25	Check the 'Don't display Agent load errors' check box if you don't want the following Warning messages to be displayed: No Agents found, No Agent OCX loaded and No Gestures.tps file found (see Runtime Warning Messages). (EXE Only)
1.26	The 'Don't display error messages at runtime' checkbox is used to hide all the error messages that are normally displayed at runtime. Instead of displaying the message, the DLL will place the message in an error group and post an EVENT:UserError to the frame of your application. There are two embed points: 'Agent - Error Event Handling' and 'Agent - Error Event Handling (After Generated Code)' at the point of handling this event in your frame procedure. The function 'ds_MsAErrorCheck' will be placed there to retrieve the error parameters (see the Special Agent Technical Manual for more details on this function). If this check-box is left unchecked then these embed points will not appear and the errors (when they occur) will be displayed as messages. (EXE Only)
1.27	In the 'Agent Options' group you can select the default options for the Agent's behaviour. These options are: 'Show the Speech balloon', 'Pace the Balloon text', 'Close the speech balloon' and 'Allow Agent Idling'. These are stored in 'msa.ini' file in your windows directory (by default). These are only the default settings, the user can double click on the agent while a sequence is running and change them if required (if permitted - more details). If you require the settings for all Special Agent applications, then you can leave the 'Apply these settings to this app only.' checkbox blank, or else check it and it will save unique settings for the current application. To override existing settings, check the 'Override existing values' check box. Everytime the program is started, it will override any settings that have been altered by the user or another program (if not program unique).You can enter a filename for the ini settings if you would rather not use the default ini file 'msa.ini'.
1.28	Press the 'OK' button to exit from the 'Extension and Control Templates' window.
1.29	Each of the local procedures will be populated with the extension template that applies to the Special Agent controls

2. The Local Procedure template for Special Agent

The 'Activate Agent functions in a Procedure' template is automatically populated by the global extension template. It does not have any prompts (normally), except the 'Omit the Agent from this procedure' check box, the 'Omit Controls' button and the 'Force This window's IMM attribute ON' checkbox on the 'General' tab (see 2.8 to 2.10).

If the procedure is the frame then the menu options form part of this template and you may need to edit the relevant details.

2.1	Select the frame procedure on which to the menu options will be placed.
2.2	Click on the 'Properties' button.
2.3	Click on the 'Extensions' button to edit the local extension.
2.4	On the Main Details tab, select a menu from the drop down list. This must be a valid menu or the application will not compile. The menu must also have a valid Clarion 'Use variable'. The agent menu 'How Do I?' will be placed onto this menu at run time. (Using the ?Help menu is normally the best)
2.5	The 'Place items directly on this menu' check box (if it is checked), will place all the sequences (that are not sub-sequences (see Changing a Sequence)) as items directly onto this menu, instead of having the 'How Do I?' menu created, with the items on it.
2.6	You can change the name of the 'How do I...' menu if you want to. The field is available to do this if you left the above check box unchecked. You can enter a variable if you would like (this is useful for translation).
2.7	The 'Disable "How Do I?" Menu' can be used if you don't want to use the 'How Do I?' menu. This will exclude all the menu populating code from the frame procedure of your application.
2.8	If you would like to run a sequence when this window is opened, change to the 'Other Details' tab and enter a sequence name (using quotes) or the name of a variable containing the sequence name in the Auto-run field. This means that if your program is a demo, it will start the sequence without the user having to do anything. There is an embed point called 'Agent - Before auto-running a sequence', where you can set the variable (for instance using an ini file) before the auto-run. This can be useful when you only want the sequence to run the first time that a user runs the program. Check out the Example Applications on specific details
2.9	Another available option is to show the current step on the status bar while a sequence is running. On the 'Other Details' tab, enter a number in the 'Display Step' field, which will indicate which status bar field to display the step on. If you don't want the step to be shown, leave this option blank or 0.
2.10	On the 'General' tab are the prompts that appear on all procedure's local agent extension template. You can check the 'Omit the Agent from this Procedure' to prevent Agent code from being generated for this procedure.
2.11	You can prevent controls being included in the sequences by clicking the 'Omitted Controls' button and adding the control to the list that appears. This will ensure that no events associated with that control will be learnt in a sequence.
2.12	The 'Force IMM attribute ON' check box will be enabled if you uncheck the 'Force IMM attribute on all windows' check box in the Agent Global Extension template. If you uncheck this, then the IMM attribute will be turned off for this window. You will need to manually inform the Agent DLL of changes in the window's size and position using the ds_SendPosition() function.
2.13	Press the 'OK' button to exit from the 'Extension and Control Template' window.
2.14	Press the 'OK' button to exit from the 'Procedure Properties' window.

3. The 'Call Agent from a Popup menu' Control Template

There is a Special Agent control template (a button), which may be used to run a sequence from a popup-menu (instead of from the main 'How Do I?' menu). This button may be populated on any window. To place this button:

3.1	Select a procedure, which requires the control template, and click on the 'Properties' button.
3.2	On the 'Procedure Properties' window, click on the 'Window' button.
3.3	On the 'Window Formatter' window, select the 'Populate' menu from the menu bar, and the 'Control Template' item from the 'Populate' menu.
3.4	Select the 'Agent_CallSequence' template from the 'Select Control Template' window, and click on the 'Select' button. The 'Window Formatter' window regains focus and the cross-and-book cursor appears.
3.5	Place the button in a suitable position by moving the cursor to that position and clicking the left mouse button. A button with the question mark icon on it will appear.
3.6	There are no options to set for this template.

4. The 'Call a Specific Agent Sequence' code template.

There is also a Special Agent code template to call a specific sequence. If you would like to use this (this may be useful if your user tries to do something they're not meant to do) in your code then:

4.1	Find the place in the code (using the embed points) to insert the code template.
4.2	Press the Insert button and from the menu tree in the 'Select Embed Type' window, select the 'Agent_CallASequence' template.
4.3	Enter the name of the sequence to call in the available field (using single quotes or a variable name) and click OK.

5. The 'Agent_JusySay' code template

Special Agent can also appear, say something and disappear. This may be useful to display short help messages or error messages. To make use of this function:

5.1	Find the place in the code (using the embed points) to insert the code template.
5.2	Press the Insert button and from the menu tree in the 'Select Embed Type' window, select the 'Agent_JustSay' template.
5.3	Enter the variable containing the words that the Agent must speak and the variable to contain the returned status (optional). Click on the OK button.

6. The 'Call Special Agent's SetLanguage function' code template.

You can set the Language file used for translating the window and the language to limit the sequences listed in the 'How Do I?' and popup menus using the code template 'Call_MsALanguage'.

6.1	The 'Language File name' prompt is the filename in the Language Path that is used for translating the Special Agent Windows and messages.
6.2	The 'Select sequences by this language' checkbox will set the Sequence Selection Limiter to the language setting found in the translation file.

7. The 'Agent_GetAvailableAgents' code template.

You can get the available agents or check for one specific agent using the 'Agent_GetAvailableAgents' code template.

7.1	Check the 'Test for 1 Agent' checkbox if you're wanting to check for a specific agent, else leave this unchecked.
7.2	If the 'Test for 1 Agent' checkbox is checked then the 'Check Agent' tab will appear with a prompt to enter the Agent name. This name should match the name in the Special Agent Character's file.
7.3	If the 'Test for 1 Agent' checkbox is unchecked then the 'Get All Agents' tab will appear.
7.3.1	If the 'Select one Agent by popup and return that agent' check box is checked then a popup menu of all the agents that are in the Characters file will be displayed and the User's choice will be returned. Alternatively the returned string will be a \| (vertical bar) delimited list of the agents in the Characters file.
7.3.2	If the 'Include Agents not loaded' checkbox is checked, then the agents that are in the Characters file, but not loaded will have a '~' preceding them in the return string, or will be disabled in the popup menu (if 7.3.1 is checked.
7.4	The 'Variable for result' field should be a string long enough to contain the returned string. If 7.1 and 7.3.1 are unchecked then your string size should be 1024 to 2048.

8. The 'Check Agent Error Group' code template

This code template calls the ds_MsAErrorCheck function. The fields prompted for are to contain the values returned by this function. The template is simply there to aid you in using this function.

9. The 'Disable Special Agent at runtime' code template

This code template calls the ds_MsAFileNames function with the parameter to clear the file names set. The Gesture and Sequence filenames are cleared, thus disabling Special Agent completely from this application. The template is simply there to aid you in using this function. It also places the necessary checks around the function call.

10. The 'Setup Agent's popup menu' code template

This code template allows you to disable some of the items from the popup menu that appears when you double-click an agent. This template allows you to enable/disable the 'Change voice' item and/or the 'Agent Settings' menu from the Agent's popup menu.

You can see an example of this in the sadabc.app example that ships with Special Agent.

Some more detail on the DLL functionality

Getting around the Sequence Window

Learning a Sequence

Changing a Sequence's Details

Printing a Sequence's Steps

Changing a Single Step's details

Running a Sequence

Stopping a Sequence

1. Getting around the Sequence Window

Press 'Ctrl-F12' (Control and F12) to bring up the sequences window. (If you require a different hotkey, you can change it in the global extension template in your application and re-compile your application. See the Setting up a default Hot Key).

The 'Sequences window' has a menubar, a toolbar and a list box. The list box shows the list of steps in the present sequence (which should be blank as no steps have been learnt). The toolbar is made up of a number of buttons (from left to right):

1.1	The 'Learn' button (with an icon of a book on it) will enter learn mode, where new steps can be added to your sequence.
1.2	The 'Run' button (with a VCR play icon on it) will run the present sequence.
1.3	The 'Step' button (with a VCR last icon on it) will step through the present sequence - one step at a time. It will post the step that is highlighted in the Sequence Window and then highlight the next step.
1.4	The 'Load' button (with a select file icon on it) will bring up the select sequence window, where an existing sequence can be selected, changed or deleted.
1.5	The 'Print' button (with the print icon on it) will print the details and events of the loaded sequence directly from this window.
1.6	The 'New' button (with a clear page icon on it) will clear the present sequence so that a new sequence can be learnt.
1.7	The 'Add Call' button (with an insert or plus sign icon on it) will add a call to another sequence at the present highlighted position in the sequence. The sequence can be selected from the 'Select Sequence' window.
1.8	The 'Edit' button (with a triangle icon on it) will bring up the change step screen, where the relevant fields can be changed. You can also do this by double-clicking the left mouse button on the step in the browse box.
1.9	The 'Delete' button (with a 'minus' sign icon on it) will delete the highlighted step from the sequence.
1.10	The 'Cut', 'Copy' and 'Paste' buttons are not available at present.
1.11	The 'Shift Up' button (with an up triangle icon on it) will shift the highlighted step up in the sequence.
1.12	The 'Shift Down' button (with a down triangle icon on it) will shift the highlighted step down in the sequence.
1.13	The 'Exit' button (with an 'exit' icon on it) will close the sequence window. The save to file routine is initiated when the window is closed.

The menu bar contains all the functions of the buttons on the toolbar in menu format. The extra items that are in the menu, but not on the toolbar are:

1.1.1	The 'Previous' menu in the 'Sequences' menu contains a list of a maximum of 6 of the last sequences that have been edited. This allows quick loading of one of those sequences.
1.1.2	The 'Save As..' item in the 'Sequences' menu allows you to save an existing sequence as another sequence.
1.1.3	The 'Renumber' item in the 'Sequences' menu will renumber the current sequence into a more easily readable order (10,20,30,etc) because (when editing sequences) the numbering soon becomes rather shabby.
1.1.4	The 'Properties' item in the 'Sequences' menu allows you to change the properties for the sequence that is loaded (without having to go via the 'Select a Sequence' window).
1.1.5	The 'Maintain' item in the 'Sequences' menu brings you to the sequence browse window which allows you to change and view sequences without affecting the present sequence that is open in the sequence window.
1.1.6	The 'Delete' item in the 'Sequences' menu will delete the present sequence that is open in the sequence window.
1.1.7	The 'Mouse Move' item in the 'Options' menu, which is an on/off toggle and is defaulted to 'On'. This option is used to switch on/off the mouse move function to allow/prevent the mouse from moving while the sequence is being run.
1.1.8	The 'Auto-Load' item on the 'Options' menu is an on/off toggle to set whether you want the sequence that was previously run or edited to load up automatically when you call the Sequence window. This is an ini setting and will be maintained when the application is closed.
1.1.9	The 'Warn On Unknown Gesture' will issue a warning when an unknown gesture is issued to the Agent. This option is stored in an ini file, but is defaulted off. It is only available to the script writer.
1.1.10	The 'Change Language' item on the 'Options' menu will bring up the 'Set Language Window', which will enable you to change the translation file used for translating the windows and the Sequence Selection Limiter (prompted: 'Saved Language'). Press the '...' lookup button next to the 'Saved Language' field in order to select a language from the language file. This will only set the language until the program is closed. When it is restarted, the language will be reset to the default (as set in the global extension template).
1.1.11	The 'Agent' item in the 'View' menu is used to open and close the agent. This is useful if you are learning a sub-sequence and the agent must be open before learning new steps.
1.1.12	The 'Restore Defaults' item in the 'View' menu allows you to restore the default sizing of the columns of the list box.
1.1.13	The 'Agents' item in the 'Setup' menu is used for agent maintenance. You can add agents here and maintain their gesture sets. (see Using 3rd Party Agents)
1.1.14	The 'Gestures' item in the 'Setup' menu is used to for gesture maintenance. Selecting this item will bring up a browse screen showing all the gestures (the defaults on the one tab and the gesture set for the currently used agent on the other) and their active state (1 = de-activated). To activate an item double click on it and check/uncheck the 'de-activate' checkbox. If a Gesture is de-activated it will not appear in the drop down list in the learn window. If a Gesture has been learnt and is subsequently de-activated it will not affect the previously learnt sequence. Note: If a Gesture ends in 'ing' (or IDLE level 3) it is a continuous gesture. You will need to learn a 'Stop' gesture in order for any other Agent gestures to be played subsequently.
1.1.15	The 'Voices' item in the 'Setup' menu is used to setup the possible voices that can be used with the agents. (see Setting an Agent's voice)
1.1.16	The 'Languages' item in the 'Setup' menu is used to access the languages that can be used for the various language settings. Selecting this option will bring up the 'Browse the Languages File' where you can view, insert, change and delete records in the Languages file. Both the Hex ID and the Language fields are critical as settings for the languages are stored by both indices. The Hex ID must be a 4 digit number and be proceeded by a capital 'H'. The standard windows language IDs and descriptions can be found in the Microsoft Agent doc: 'progagentcontrol.doc' (under the #LanguageID section).
1.1.17	The 'Excluded Events' in the 'Setup' menu is used to setup events that should not be recorded into a sequence. You can set an event for a specific control type (like mouseIn on regions) or for all types (move/size) and when this event is trapped, it will not be saved into the sequence. This does not pertain to existing sequences that have these events in already. These events will still be sent when you run those sequences. If this item is disabled, then you have not set a filename for the ExcludedEvents file in the Global Extension Template.
1.1.18	The 'Agent Docs' item in the 'Help' menu is a URL link to this document on the CapeSoft website (by default).
1.1.19	The 'Set to local path' item in the 'Help' menu will allow you to set the URL link for the 'Agent docs' item (above) to a local path if required. To reset the path to the CapeSoft website, click on this item and press the cancel button on the Filedialog window that appears.

You can resize the sequence windows and the column in the list box to suite your needs and taste. When the sequence window is opened it will automatically open in the size in which it was previously closed.

You can see where the Sequence file that you're currently using is stored. On the sequence window below the browse you will see the details of the path and the file name where the sequences are.

Note: The Agent events are not time dependant because of the varying length of the Agent animations, thus the delay field cannot be edited for the Agent events.

2. Learning a Sequence

In the sequence window, click on the 'Learn' button. If there are other steps already in the sequence, the option will be given to start learning at the highlighted position on the list box ('Here'), at the beginning of the sequence ('Beginning') or at the previous step that was posted during a run/step/learn ('Previous'). This will enable steps to be inserted into any point in the sequence. There is also a 'Cancel' button to abort learning. If this is a new sequence then the Update Sequence window will appearing requiring some information before you begin learning (see Changing a Sequence).

Tip	When inserting steps into an existing sequence, ensure that the necessary windows have been opened before learning (i.e. you must be at the same place in the program when you start learning as the previous step in the sequence).
Note	You can resize the Learn Sequence window to suite your needs. You may find that the window is too small to contain all the text that you want the agent to say.
Note	When inserting steps, highlight the next step when pressing the learn button and the steps will be inserted above the highlighted step (unless the last step is highlighted then the steps will be added to the end of the sequence).

The 'Learn Sequence' window will appear, which contains a drop list box, a number of buttons and an entry field.

2.1

The Drop list box contains a list of all the possible agent gestures. Once you have selected a gesture for the Agent, press the enter key.

Note: If a Gesture ends in 'ing' (or IDLE level 3) it is a continuous gesture. You will need to learn a 'Stop' gesture in order for any other Agent gestures to be played subsequently. You may learn program events while the Agent is in continuous gesture mode though.

2.2

The entry field is used to type words that the agent will say. (Note: the agent must be opened before gesturing or speaking). After entering the words for the genie to speak, press the enter-key.

Note:	There are some characters which will cause the Microsoft Agent to ignore a 'Say' command (`<>{}[]&*%^$#@ and characters with ASCII values > 128). These should not be used in this field. The double quotes " are reserved for tags only. Using double quotes incorrectly will abort the 'Say' command. See Useful Agent Speech Tips for more details on speech tags.
Hint:	You can use punctuation to vary the agents voice.

2.1.1	The 'Agent' button (with an icon of a lamp on it) is used to open and close the agent. When you open the agent for the first time in a new sequence, a pop-up menu will appear. This menu shows the available agents allowing you to select an agent for this sequence. If you select an agent that is not loaded, then the first available agent will be used instead.
2.1.2	The 'NoRecord' button (with an icon of a cassette crossed out on it) is used to play the next gesture without recording it in the sequence. This is useful if you're not completely familiar with all the agent gestures and are unsure of which gesture you would like to insert in the sequence. You can try out a gesture before recording it. This button will only apply to gestures, all other events will be recorded in the sequence, whether this button is pressed or not.
2.1.3	The 'NoLearn' button (with the icon of the book crossed out on it) is used to stop learning mode and return to the sequences window.

While this window is open, all the relevant steps that are posted will be added to the sequence in order. Menu-items can be clicked, and fields entered, etc, etc and it will be saved to the sequence. You perform manually what your sequence will do at run time, and Special Agent will record what you do. When the sequence is run, then Special Agent will play back the events that it recorded to your program.

Note: Special Agent does not directly record menus being dropped down (as this is handled by windows) you need to click on an item in the menu in order for the menu to appear when the sequence is run.

NB: Do not learn a step in your sequence that requires an interface with a system message as this will hang your application. Do not learn a step which will run a sequence or issue a command to use the code template 'Agent_JustSay'.

3. Changing a Sequence's details
In the 'Sequences Window', click on the 'Properties' item in the 'Sequences' menu. The 'Changing a Sequence' window will allow you to:

3.1	Change the sequence name (that appears on the 'How Do I?' menu),
3.2	Change the sub-sequence status (if this is checked, the sequence will be omitted from the How Do I Menu and Sequence Popup Menus).
3.3	A drop list will allow you to change the Agent that should be used in the sequence (if you would like another Agent other than the one that you learnt the sequence with).
3.4	The Time Limit Option allows you to set a maximum time between steps. You may find that most of the time between steps is too high. You can set a sequence maximum, and then override this default on the individual steps that require a longer delay.
3.5	Change the description (the message that is displayed on the status bar when the sequence item on the 'How Do I?' menu is highlighted), on the "Details" tab.
3.6	The 'Start in' procedure (on the "Details" tab) is the starting point of the sequence. In the case of a frame with a splash screen, the starting point of the sequence is often taken from the splash screen and not the frame. You edit the name of the procedure so that it appears in the 'How do I?' menu if this is the case.
3.7	The 'Application' field (on the "Details" tab) allows you to edit the sequence's parent application. This is useful if you have a multi-DLL application and you require that the sequence starts in one of the DLLs.
3.8	The 'Override Voice' field will allow you to override the default voice that the agent uses. This can be left 0 in order to use the default voice. If you would like to change the voice for the specific agent globally, then change the voice for that agent rather than changing it every time you use it and leave this field 0.
3.9	Use the 'Language Field' to set the language of a sequence. This is not necessary if the sequence file contains sequences in only one language. However if you ship the same sequence file with your application to countries with different languages then use this option so that only those sequences pertaining to the language (as setup in the translation file) will be displayed in the 'How Do I?' menu. Otherwise leave the field 0.

In this screen you can also delete sequences and fix old sequence files. The 'Fix App & Proc fields to lower case' button will check each record in the Sequence file for application and procedure names that have upper case letters in them and change them to lower case. From Version 1.20, Special Agent converts the application and procedure names that it receives to lower case.

4. Printing a Sequence's Steps

In the 'Sequences Window', click on the 'Load' button. A list of sequences (that have previously been learnt) will appear on the 'Select Sequences' window. To print the Sequence's steps, highlight the sequence and click on the button with the printer icon on it.

5. Changing a Single Step's details
In the 'Sequences Window', select the step that you want to make changes to. Click on the 'Change' button (the one with the triangle on it). The 'Make Changes to an Event' window will appear allowing you to change the following:

5.1	The comment - describes the step
5.2	The time - (hidden for Agent steps and steps that use the default timer as the maximum) sets the delay before the next step. To unhide this field click on the 'Ignore Default Timer' check box.
5.3	The value field - is used for text entry, tab selection, Agent speech text, etc. If you've made a spelling mistake in your Agent speech (for example) you can edit it in this field.
5.4	The 'No Mouse Move' check box - gives you the option not to move the mouse for this specific step. This is only applicable for events that use this function (like selecting fields, pressing buttons, changing tabs, etc.)
5.5	The 'Agent Position Co-ordinates' - are used if the step is an 'Agent Move' step. You may edit the co-ordinates that the Microsoft Agent moves to. These co-ordinate fields are otherwise hidden.
5.6	The 'Ignore Default Timer' checkbox allows you to override the sequence time limit for this specific step. This is not applicable for agent steps.
5.7	The 'Item Control' check box is used for sequences that were learnt before Version 1.16. This changes the event that is saved from an EVENT:Accepted to an EVENT:UserItem, which enables the menu drop down. If this is left unchecked, the browse (for example) that the item selects will just appear, without the menus dropping down and the required item highlighted.

Changing a step's details will cause the step counter to reset, so when the next step command is issued, it will step through the sequence from the beginning.

6. Running a Sequence

A sequence can be run in 3 different ways:

1.	The sequence can be run from the 'Sequence Window' by loading the sequence and clicking on the 'Run' button.
2.	Select the 'How Do I?' menu and then select the sequence to run from this menu. Note: This will only apply to sequences that start in the window where the menu appears and that are not sub-sequences.
3.	Press the 'Call Sequence' button (the Agent's control template), if it has been populated, and select the sequence from the list that appears. Note: This will only apply to sequences that start in the window where the control appears and that are not sub-sequences.

7. Stopping a Sequence
To stop the sequence at any point, double click on the agent. The sequence will pause and a popup menu appears allowing you the option to continue or stop the sequence. If the sequence is being run from the sequence window, the sequence window will reappear and the next step will be highlighted in the list box. To continue the sequence after pausing it, you can double-click on the Agent again and select the continue option from the popup menu. The Agent will complete the step that he is currently busy with before pausing or stopping.

Note: Special Agent does not support Dragging and dropping as yet, and does not support VBX, OCX, OLE or EIP controls. All other controls are supported and most functionality has been catered for.

Example Applications

There are a few example applications which will aid you in the use of some of the Special Agent features. You fill find these in the Clarion\3rdParty\Examples\Agent directory. All the example applications are in their respective sub-directories, although they use the common data in the data directory.

1.	There are two example applications in the SADemo directory: one using abc templates (SADabc.app) and one using legacy templates (SADleg.app). These applications illustrate:

1.1	Auto-running sequences (i.e. running an introductory sequence at program start-up) and ways of disabling the auto-run at run-time.
1.2	Using sub-sequences effectively.
1.3	Using the Special Agent Control template to run sequences from a popup menu.
1.4	Ways of demonstrating the different characters that are loaded.
1.5	Handling the Special Agent run-time errors in the EXE.
1.6	Completely disabling Special Agent at runtime (you need to run the example program more than once to try this feature).

There is one example application in the SAMulti-DLL directory made up of 4 applications (SAMLE.app, SAML1.app, SAML2.app and SAML3.app), which use the legacy templates. These applications illustrate the use of Special Agent in a multi-DLL application. This application does not include the full functionality that the SADemo does. You must compile the applications in the following order:

SAML1.app, SAML2.app, SAML3.app and then SAMLE.app

You can run the exe SAMLE.exe once you have done the complete compile.

3.	There is one example application in the SATranslation directory, which uses abc templates. This application illustrates:

3.1	The translation of the Special Agent windows into another language. (Checkout the Portugue.irf file in a text editor to see how it's done)
3.2	The use of the Sequence Selection Limiter

Using Third Party Agents

They're Here!!

Now you can pick from a wide range of characters to use as your demonstrator. From the disgusting Wartnose to the pristine James the Butler you can select a character that will suite your needs and your clients. From version 1.25 onwards you can use a 3rd party agent or agents other than Genie, Robby, Peedy or Merlin. A good website to start looking for other agents is the www.msagentring.org website. You will find a host of free agents that you can download directly or go to the sites of their creators to buy some of their agents that are for sale.

Once you've downloaded an agent, run the exe from the download, making it available for use. You will still need to run msagent.exe and tv_enua.exe in order to install the Microsoft Agent OCX and the text to speech engine.

Using Third Party Agents in your Program

Gesture set Troubleshooting

What files to use

Exporting & Importing gesture sets

Using them in your Program

Run your program (with the Special Agent template added) and bring up the sequence window (press the Sequence Window Hot key). In the sequence window you will find an "Agents" item in the "View" menu. Selecting this will bring up the Agents Browse screen and you will see all the agents that are installed and that you have added manually (including the one that you have just installed). Highlight the agent you have just installed and click on the "Change" button. Do not change the Character name as this is the name that the OCX uses to identify the character. If you would like to use the default gesture set then do not enter any gestures in here. Many of the characters use gestures apart from or far fewer than the default gesture set so it is useful to enter an independent gesture set for each character. As many gestures that you enter and do not make "InActive" are the ones that will appear in the Gestures drop down box as you are learning a sequence (see Learning a Sequence).

You will find a "Gestures.tps" file in the clarion\3rdparty\examples\agent directory which has a complete gesture set for all of the free characters downloadable from www.msagentring.org

Gesture set Troubleshooting

It's useful to run the sequences with the "Warn On Unknown Gesture" check on after entering a new gesture set as this will indicate any invalid gestures as they are being played. You can then immediately be notified of the invalid gesture and edit the gesture set. Normally (with the "Warn On Unknown Gesture" unchecked) if an invalid gesture is issued to the Agent, it will just skip over the gesture and continue with the next.

What files to use

It's normally best to use a single central "Gesture.tps" file from where you can access the characters and their gesture sets. This means that you don't have to export and import the character sets to each of your "Agent.tps" files that your different programs use. You will, however, need to ship the "Gesture.tps" file with your exe to ensure that the correct character is used for the sequences that you have learnt. If you would prefer to ship just the one file you can incorporate the characters and their gesture sets into the "Agent.tps" files. (How do I set this up in my program?)

Exporting and Importing gesture sets

There are "Export" to text and "Import" from text functions available in the "Browse Characters" window. This is useful if you are maintaining more than 1 gesture set. In the sequence window (How do I get there?), select the "Agents" item from the "View" menu. The "Browse Characters" window will appear. Select the Character which you wish to export and click the export button. Enter a file name in the filedialog box provided and click "Export". If you would like to import a loaded character's gesture set, then you will need to first delete the character (you cannot have two gesture sets for the same character) before importing from the text file.

Agent Voice Changing

Note: You must install the Microsoft Agent Speech Control Panel (spchcpl.exe) in order to be able to change the agent's voices. You will need to install this on every PC where voice changing is required.

Before you can manipulate the agent's voices you will need to set up a voice file.

1. Setting up a voice file

To do this you go to the sequences window (How do I get there?) and click on the 'Voices' item in the 'Setup' menu.

A Browse screen will appear showing you all the voices (if any) that you have inserted. This does not mean that these are necessarily all the voices that are loaded, but merely the ones that have previously been inserted into the Special Agent's voices file.
Click the 'Insert' button to add a new voice.

The 'Adding a Voices Record' window will appear allowing you to add the details of the voice. The name of the voice is the field that will be used to select and change voices.

1.	The 'Voice Code' is the unique ID which Special Agent uses to identify the voice. This is auto-numbered.
2.	The 'Manufacturer' is the creator of the Speech engine ('e.g. Lernout & Hauspie')
3.	The 'Name' is the description for the voice that will appear in the popup menu if the user wants to change the voice for an agent.
4.	The Gender indicates whether the voice is a male or female voice.
5.	The 'TTSModeID' must be accurate. This is the manufacturer's unique identifier to activate this voice.
6.	The 'Language' is the language setting for the voice. Although this is not presently necessary, it will be supported in future versions of Special Agent.

2. Changing the Agent's voice

The Agent's voice can be changed in the following ways (in priority order):

2.1	At runtime, while a sequence is running, you can double-click the agent and select a voice from the popup menu. This list is obtained from the Voices file in the Sequence window. This voice will then be fixed for that agent in an ini file, so that whenever that agent is used (in a Special Agent application) on the selected voice will be used. There is a default voice option, which will eliminate the voice being changed from the ini file when the agent is run.
2.2	The voice can be set for this specific sequence, so that you can override the default voice for the agent in this sequence. This is useful if you have one sequence file with sequences in different languages in it.
2.3	The default voice for an agent can be set in the Characters file, so that if an agent has an irritating voice, or an uncharacteristic voice, you can change it so that when that agent is used it defaults to a different voice to the manufacturer's default.

Important Note:
Not all the speech engines support the speech tags used in the standard Lernout & Hauspie speech engines.

Useful Tips and Info

Stopping or pausing the sequence

Turning Mouse Moving off for running sequences

Turning Mouse Moving off during testing

Timer details

Sub-sequences explained

Calling sequences and the 'How do I' menu

Drop-Lists and Drop combos - some hints

Starting the Agent in a different position

Setting the Agents' options

1.	To stop or pause the sequence while it's running see Stopping the Sequence.
2.	If you don't want the mouse to move for a specific step (like a hidden region) you can check the 'No Mouse Move' checkbox, which will prevent any mouse movements during this specific step.
3.	Note: The Mouse Move item in the Sequence window is only used to prevent the mouse from moving during testing. It isn't saved and once you close the window, this setting will be lost. The mouse will only move if (when you're learning the sequence) you actually click on the control. If you use the hot key, or the tab to get to the control, the mouse won't move when you're running the sequence.
4.	The Timer is measured in hh:mm:ss and can be set for any steps, except the Agent steps. This will set the delay period after the step is processed, before the next step is issued. The Agent steps are dependant on events passed to the DLL from the Agent OCX, as the gestures, speaking, opening and closing, all have different time periods, thus the timer is ignored for these steps (you will see that it appears as 00:00:00) when the step is learnt. If you want to change the time for a step you can use the Edit In Place function to shorten or lengthen the delay. The individual times can be overridden by the Time Limit option in the Sequence Details see Changing a Sequence.
5.	You can learn a few sequences and string them into one. This is useful if you're wanting to use parts of the sequence elsewhere (like an all demo, and a demo of a browse screen). You can use different agents in sub-sequences, string them together into one, and have a sequence that uses different agents for different tasks. You must close the agent before opening the next one though.
6.	All sequences that start on the Frame will appear in the 'How Do I?' menu unless they have the 'Sub-Sequence' option clicked on. Similarly if you have used the 'Agent_CallSequence' control template on your screen and you don't want a sequence to be activated from that button, check the 'Sub-Sequence' option on. Thus the 'Sub-Sequence' option will make your sequence hidden from the end user. To do this, go to Changing a Sequence.
7.	If you want a Drop List/combo to stay dropped while selecting a record (while playing a sequence back), check the NoMouseMove option ON on the Dropdown and NewSelection steps to that Drop List/combo.
8.	If you would like the Agent to appear somewhere other than the top left corner of the screen, then when you learn a "StartAgent" command (i.e. click the "Open the Agent" button on the Learn window) immediately move the character to the place where you require it to open. When you run the sequence, the character will be opened in the position you required.
9.	The user can set some specific options for the Agent on their PC if they would like to. If you're running a sequence, you can double-click on the agent for the Agent's pop-up menu, there is a sub menu item called 'Agent Settings' (which can be disabled if preferred - thus preventing the user from altering this). In this sub-menu are 5 options: 1. 'Show Speech Text Immediately' - if you check this option then the agent's speech text will immediately appear in the speech bubble, instead of appearing as it speaks the text. 2. 'Keep Speech Bubble Open' - if you check this option, then the agent's speech bubble will remain open after it has finished speaking. The speech bubble will close if you move the agent, click on it, or close it. 3. 'Show Speech Balloon' - if you check this option, the agent's speech balloon will be displayed with a speech command. If not, then only the audio is heard with no balloon being displayed. 4. 'Show Property Sheet' - opens the property sheet, which allows you to set some of the agent's properties. 5. 'Allow Agent Idling' - allows the agent to perform idle gestures when no command is issued to it.

Useful Agent Speech Tags

Mapping Balloon (displayed) Text to spoken text

Emphasizing specific words while speaking

Changing the speed that the agent speaks the words

Changing the character of the voice (whisper, etc.)

1. Balloon Text and Spoken Text

There is often the problem that Special Agent will pronounce things incorrectly. This leaves you with the choice of compromise in the Agent's voice or the display of the sentence in the balloon using strange spelling. This is solved by the \Map tag in the actual sentence spoken. The syntax is

'\Map="SpokenTextString"="BalloonTextString"\

where SpokenTextString is a valid Visual Basic string for the phonetics of the voice, while BalloonTextString is a valid Visual Basic string for the text displayed in the balloon.

Example

One of CapeSoft's products is Makeover and it users a program called "Styler" to enable you to edit the styles of your screens. Special Agent pronounces "Styler" as "Stealer", which is noticeably incorrect. To pronounce this string correctly and have the correct text displayed in the balloon, the Clarion string that should be used for the Agent speak command is as follows: (Note the two double quotes preceding and following each string.)

'You can use the program \Map=""stiler""=""Styler""\ to edit your screen'.

2. Emphasizing words

You can use the \Emp\ tag to emphasize a word in a sentence.

Example

In the following example the words "Special" and "Agent" will be emphasized.

'\Emp\Special \Emp\Agent is simply the best help tool there is around.'

3. Changing voice speed

If you are finding that there is a specific use for increasing or decreasing the speed of the sentence, you can specify the speed at which the words are spoken by using the \Spd tag in the sentence. Speed is indicated in words spoken per minute. The slowest speed is 50, while the maximum speed is 249 (the normal default speed is 150).

Example

In the following example the words "Special Agent" will be spoken slowly.

'\Spd=70\Special Agent \Spd=140\is simply the best help tool there is around.'

4. Changing voice character

If you would like to change the character of the way that Special Agent speaks, you can use the \Chr tag. You can make Special Agent whisper, speak in monotone or speak normally (You mean you thought Genie normally spoke in monotone? <gr>).

Example

In the following example the words "Special Agent" will be whispered (Note the two double quotes preceding and following the string description).

'\Chr=""Whisper""\Special Agent \Chr=""Normal""\is simply the best help tool there is around.'

International Language Support

There are a number of aspects involved in supporting languages other than English.

1.	The Special Agent DLL windows need to be translated so that the sequence writer can understand the different prompts.
2.	The Special Agent DLL messages need to be translated so that both the sequence writer and the end user can understand the respective messages.
3.	The Agents need to be able to talk in the new language (i.e. pronounce the words correctly).
4.	The end user must only be able to play the sequences that are in their respective language.

1. Translating the Special Agent DLL Windows and Messages

1.1	You will need to set a translation path and a translation file in your EXE. You can do this in the global extension (in your EXE if this is a multi-DLL project).
1.2	If you are supporting multiple languages then you can change the language at run-time using the 'Call_MsALanguage' template in your code. You should have one translation file for each language that your program will use. You can change the language file from the Sequence Window at runtime using the 'Change Language' item.
1.3	When you run your program, the translation file will be created (if it is non-existent) as an ini-type file. There will be a section (e.g. [Main]) for each window with an equate for each of the translatable properties of each control. Thus a button may have 3 properties: one for the text on the button, one for the tip and one for the statusbar message. If the translation engine does not find an entry for a translatable text, then it will create one and put the default English text into the equate.
1.4	Once the entries are placed in the ini file, you will need to edit these with a text editor. Example: ?Cancel=Cancel would appear in the text file as the default text for the Cancel button. To change the text to Portuguese edit as follows: ?Cancel=Cancelam
1.5	You will need to open each window at runtime in order to create the necessary translation entries into the translation file. If you check the 'All Messages into Translation File on Start-up' in the global extension template then the messages that Special Agent uses will be written into the translation file when your program is run. This makes translating the messages much easier as you don't have to force the messages to occur in order translate them.

2. Changing the Agents' voices

2.1	You will need to create a voices file.
2.2	You can then Change the Agent's voice to be a voice that is compatible with the language pronunciation.

3. Setting the Sequence Selection Limiter

The Sequence Selection Limiter is a LanguageID that can be set to limit the sequences (that the user has access to) to that Language. You can thus have sequences in different languages in the same sequence file that you can ship with your application. You can then allow the user to select a language and the sequences that can be selected from the 'How Do I?' menu and the popup menus will be restricted to the language that the user selects.

3.1	You will need to set the language setting of the sequence. You can do this in the Sequence Properties.
3.2	There are a number of ways of setting the Special Agent DLL's language setting.
3.2.1	You can set the default language setting in the Global Extension Template. When your program is run, the Special Agent DLL will be set to this language.
3.2.2	During sequence creation it is useful to be able to change the default language so that when you create a sequence it will be set to that default language automatically. You can do this in the 'Change Language' item. This will be reset to the default (as set in the Global Extension Template) when the program is closed. Thus you can set the Saved Language to French, learn all the French sequences, and then continue to Spanish, etc.
3.2.3	You can use a code template to change the language setting in the Special Agent DLL. For example, you could attach instances of this template to a number of buttons (e.g. 'French','Spanish','English',etc) and when the user clicks that button, the Sequence Selection Limiter will be set to the specified language.

Runtime Error Messages

Each message can be translated (if required) in the translation file. Thus each error message is numbered for ease of identification. The number appears in brackets in the message heading.

(1) Error: You must first load a valid sequence. The DLL is trying to perform function on a sequence when no sequences are loaded. First load a sequence before proceeding.

(2) Question: Would you like to restore the link to the|capesoft page for the agent help docs? The hyperlink to the Special Agent docs is not traceable as the Agent docs are not where they are expected. If you select 'Yes' then the hyperlink will be replaced by the link to CapeSoft's page instead of trying to find the docs on your local machine.

(3) Note: Feature not yet available. You have attempted to perform a function that is not available in the present version of Special Agent.

(4) Suggestion: Renumber before shifting. A message that is now unused.

(5/7) Note: Error moving step up/down: You are trying to move a step in the sequence up/down in the sequence. This means that the sequence has somehow got corrupted or you trying to move the step up/down when it is at the top/bottom of the sequence. Quit the program (you may also have to restart Windows) and restart the program again.

(6) Error: Error getting step from the queue. An error occurred while trying to access the sequence items files and so the step could not be obtained. This could mean that the file is corrupt or that the file is in read only mode.

(8) Error: Error getting from the stack or Error obtaining previous pop-point: <error>: The sequence has one (or more) calls in it (i.e. it calls other sequences from it). When it returns from the call, it cannot locate the previous sequence to return to. This is a stack error so there may be a memory-handling problem. Returned errorcode is <errorcode()>* (where errorcode() is the error that occurred while trying to access the record from the stack).

(9) Error: Error getting next Sequence: <error>: The sequence has one (or more) calls in it (i.e. it calls other sequences from it). It cannot load the sequence that is called. This usually means that the AGENT.TPS file is corrupt or that the path is changed during runtime. Returned errorcode is <errorcode()>* (where errorcode() is the error that occurred while trying to access the record from the file).

(11) Note: You must save the sequence name first|before learning steps in the sequence. The 'Cancel' button was pressed when learning a new sequence when the sequence details are required.

(12) Note: Renumber a success. Renumbering of the sequence is completed abnd was successful.

(13) Special Agent Warning: Gesture not known for this agent: <Gesture>. A gesture was issued to the current agent that it does not recognize.

(14) Error: Error getting thread for <Procedure>: This sequence was started in the incorrect procedure, the procedure wasn't opened, or the procedure was closed prematurely. This is usually a learn sequence error. Learn the necessary steps to get to where you want to start (e.g. open the Microsoft Agent before you issue commands to it). Returned errorcode 152*.

(18) Delete Sequence: There is a sequence that has no steps in it.|Would you like to delete it? <Seq:Name>. A 'Yes/No' option that allows you to remove a sequence that has been created without any steps in it.

(19) Error: You must enter a valid filename|[errorcode()] [error()]|[clip(TEX:Text)]. You are attempting to export/import to/from an invalid/non-existant text file. Re-enter a correct text file and proceed.

(20) Error during import loop: This file is not included in the routine:|[clip(TEX:Text)]|Abort loop?. While importing from a text file, the import routine came upon an illegal import command/structure in the file and is not sure what to do with it. You may abort if this is not a valid import text file.

(21) Warning: You will need to import the Sub-Sequence:|<Sub-Sequence name>|so that this sequence can run correctly. You are importing a sequence that has a call to a non-existant sub-sequence. You must import the sub-sequence as well in order for the sequence to run correctly.

(22) Warning: Cannot find the required/selected voice. You are trying to use a voice that is not existant in the voices file any more (e.g. the voices file has been deleted or a sequence has been imported and the voice that the sequence requires is not in the voices file.

(23) Warning: Cannot find the required/selected language. The Agent is attempting to set the language, but cannot find the specified language in the language file. The cause of this problem could be a mis-placed language file (gestures.tps), an incorrect language specification (i.e. the language is named 'English' instead of 'English (USA)') or an outdated/new language file (gestures.tps) which does not contain the language specified.

(24) Warning: Cannot Find this Sequence. You've got a call in your routine to run a sequence that has been deleted or renamed. This is either handcoded in or using the Code Template 'Call a Specific Agent Sequence'. Check for the line in your source ds_AgentInterface(parameters).

(25) Error: Error accessing the [clip(SequenceFN)]|[errorcode()] [error()]. An error occured while trying to read a record from the Sequence file. The error is displayed in the Message Box.

(26) Error: Error adding Sequence step.|[errorcode()] [error()]. An error occurred while trying to save an event in the sequence. The file and error are displayed in the message box.

(27) Error: Cannot save records to the Position file in:|[clip(SeqPosFN)]. While attempting to add co-ordinates to the position file (a window re-size or move event), there was a file error.

(28) Error: Error converting old file structure to new file structure. The sequence file structure that you are currently using is the old file structure (pre version 1.16). While attempting to up grade to the new file structure, there was a file error.

(29) Error: Menu item incorrectly mapped. You've handcoded your menu/item mapping and have not ended your map with an E, or there is an E occuring before the end of the string. You may only have one E in the string.

Runtime Warning Messages

(15) Special Agent Warning - The Microsoft Agent OCX is not loaded. You will not be able to run any of the help sequences. Run the MsAgent.exe and the tv_enua.exe programs to install the Microsoft Agent OCX.

(16) Special Agent Warning - Cannot find the Agent Gestures file or no Characters found in the Gestures file expected at: <FilePath>. There are <NumberOfAgents> Agents installed. Would you like to create a new gestures file?(This may use different Agents in previously learnt sequences). If the Yes button is pressed, then all the agents installed will be added to the Gestures file, but they will have no gesture sets, so you will only be able to learn gestures from the default gesture set for each character until you create the respective gesture set. However, existing sequences will be played as they were created (with the correct gestures), except the Agent used in the running of the sequence may be different to that with which the sequence was originally learnt. If the No button is pressed, then a blank gesture file is created with no characters/ gestures. When a sequence is run 'Genie' (or a random other character if Genie is not installed) will be used in the sequence.

(17) Special Agent Warning - You do not have any Microsoft Agents installed. You will not be able to run any of the help sequences without installing a Microsoft Agent. Contact Your supplier for details. You must run at least one of the <agent>.exe character install programs so that your sequences will run.

Note: If you have the ' Don't display error messages at runtime' checkbox in the global extension template checked you can use these error codes together with the ds_MsAErrorCheck() function to handle the errors. The returned errorcode appears in the second field of the group returned in ds_MsAErrorCheck(). Check out the example application 'msaabc.app' for examples on Agent Error handling.

Error Messages (Compiler)

File not found: <path>\you_need_to_change_your_app_to_32-bit.lib: This occurs when the project has been set to 16 bit instead of 32 bit. You'll need to edit the project properties and change it to a 32 bit project.

DS_AgentControlQ is unresolved in file c:\clarion5\obj\<filename>001.obj: You could have misplaced the c5(5)msax.lib file or the c5(5)msaxl.lib file and so the project can't find the definitions for the Special Agent functions.

If you have not selected a menu item for the 'How do I' menu, three compile errors will be generated. If you edit these errors, the errors will explain how to rectify this problem.

If you have not assigned a variable to a check box, an error will be generated. Editing this error will provide the instruction as to rectify the problem.

Frequently Asked Questions

	Audio Issues
1.1	I cannot get the Agent to speak. The speech text appears in the bubble, but there is no audio.
1.2	I don't want my users to be able to change some of the agents settings (like voice, speech, bubbles, etc). How do I do this?
1.3	I don't want the speech bubble to appear, how do I do this?
	Translation Issues
2.1	If I'm going to use (for eg.) Spanish, must I use the Call_MsALanguage function? If so How.
2.2	Where in the template must I establish that I'm going to use (for eg.) Spanish as a language?
2.3	I am translating and using a number of agents, but one agent (eg Merlin) always speaks in Spanish
	Timer Issues
3.1	I have long delays in my sequence
3.2	What is the difference with the default timer on/off?
3.3	What are the timing units, hours, mins, secs?
	Position Issues
4.1	How do I position the mouse?
4.2	When I learn an 'AgentMove' step I often get the position wrong.
4.3	How do I open the Agent in a position other than the top left hand corner?
4.4	I tried to issue ds_SendPosition right after positioning the window, but to no avail.
	Startup and Setup Issues
5.1	Can I get SA to start working via a BUTTON on the MAIN procedure without having SA ?attached? to a menu item? If so how?
5.2	If I have a terminal client session open with the terminal server and I run my application in that session it does not see MsAgent.
5.3	Will you be able to run Special Agent if you distribute the agents.tps and gestures.tps to the client's machine and then run the agent on the local machine?
5.4	Not all my sequences appear in the 'How do I?' menu. Is there a limit to the amount of sequences that appear in the 'How do I? menu?
5.5	None of my sequences appear on the 'How Do I?' menu
5.6	How should one use sub-sequences?
5.7	When I press CTRL-F12 the sequence window does not appear
5.8	I've already used Ctrl-F12, what must I do now?
5.9	When I run my application there is no 'How Do I?' menu.
5.10	I can't put Special Agent on the Help Menu.
	Sequence Running/Learning Issues
6.1	My Sequence often GPFs my program and comes up with PUSHScope/POPScope errors, as well as 801 Bind errors.
6.2	If the Agent does one of the gestures ending in 'ing' it does not do any other gestures, but continues doing that one. How do I get it to stop?
6.3	I would like to know when my sequence has finished running. What is the best way to find out?
6.4	My sequences hang when I open one of my windows. The sequence stops and the agent 'falls asleep'.
6.5	My menus don't always drop down in the sequence that I've learnt
6.6	Sometimes my text does not input
6.7	When I run my sequence, I get an error message "Error getting thread for The Agent".
6.8	I would like to run a sequence automatically when my program starts, how can I do this?
6.9	The Agent does not always select the correct item in the menu during sequence play-back
6.10	I am having problems with figuring out how to "Learn" opening menus, selecting tabs etc.
6.11	I have a sequence of ds_AgentDoGesture() and ds_ImmediateAgent() commands together. Some of the ds_AgentDoGesture() commands are not being done.
	Registration Issues
7.1	I bought Special Agent for Clarion 5 but I now need the version for Clarion 5.5 (or later). How much does it cost...
7.2	So how do I register?

1.1 I cannot get the Agent to speak. The speech text appears in the bubble, but there is no audio.

Step 1: You may not have a text-to-speech engine loaded (like tv_enua.exe). Load the engine and try running your sequence again.

Step 2: If you are running windows XP then you need to install the SAPI 4.0 Runtime (spchapi.exe freely downloadable from Microsoft http://activex.microsoft.com/activex/controls/sapi/spchapi.exe ).

Step 3: If you've tried steps 1 and 2 then you may have set an invalid voice for that agent then you may have a situation such as this. The agent's voice is set in 1 of 3 ways. Clear all 3 ways and then re-attempt the sequence. If you require a specific voice, then ensure that the TTSModeID for that voice is correct and that the voice is in fact loaded.

Step 4: If you've tried steps 1 and 2 then you have probably changed voices without installing the Microsoft Speech Control Panel (spchcpl.exe). Run the installer to enable the voice changing.

1.2 I don't want my users to be able to change some of the agents settings (like voice, speech, bubbles, etc). How do I do this?

Answer: You can insert a call to the ds_DisablePopupOptions function somewhere in your program by using the code template: 'Setup Agent's popup menu' or using the function directly and setting which item must be disabled in the popup menu.

1.3 I don't want the speech bubble to appear, how do I do this?

Answer: There are 3 ways of doing this (depending on the application).

1. To do this by default you can clear the 'Show Speech Balloon' check box that occurs in the Global Extension template,
2. To do this at runtime you can double click on the Agent (while running a sequence) and select the 'Show Speech Balloon' item on the 'Agent Settings' menu that appears.
3. To do this manually in your program, you can use the function ds_SetAgentOptions() to force the balloon off.

2.1 If I'm only going to use (for eg.) Spanish, must I use the Call_MsALanguage function? If so How.

Answer: Call_MsALanguage is only for applications that support multiple languages. For example if you ship your program in Spanish, French, Portuguese and English, then you could prompt the user on startup for a language of their choice and then set the Special Agent's language to that language using the Call_MsALanguage function. You could then set your default language in the global extension to the preferred one. But in the case of using only one language, none of this is necessary. See the SATabc.app example in the clarion\3rdparty\examples\agent\SATranslation directory for a practical guide to use this function.

2.2 Where in the template must I establish that I'm going to use (for eg.) Spanish as a language?

Answer: If you're only going to use Spanish then that makes things a bit easier. You don't need to worry about setting the language if you're only going to use one language. You can set the translation file (in the global extension template) so that the messages and Special Agent windows will be translated. You'll need to translate and ship the translation file though. There is an example of a translation file in the clarion\3rdparty\examples\agent\data.

2.3 I am translating and using a number of agents, but one agent (eg Merlin) always speaks in Spanish, no matter what I set the language in the sequence to. How do I get him to speak in English again?

Answer: Take another look at the Changing the Agent's voice . It sounds like you have set the agent's voice using the 'Change Voice' option in the double-click on the agent (No 1 priority in Changing the Agent's voice). If you have set a voice for an agent, this voice is stored in an ini file, so whenever you use that agent on your machine, it will speak in the voice that you've specified. If you select the 'Use Default' then this deletes the setting from the ini file, and the next time the agent is used, it will use the next priority voice. If you want to get back to the original voice, you need to remove all 3 possibilities that could be changing the voice.

3.1 I have long delays in my sequence. How do I edit the time?

Answer: (see Changing a Step). Alternatively you can edit the field directly in the sequence list box on the 'Sequence Window'. See Useful Tips for more info on the timer.

3.2 What is the difference with the default timer on/off?

Answer: The 'Ignore Default Timer' only works for non-agent steps. If you've set a default time limit for the sequence (like 1 second), this will ignore all the times that it's recorded and that are greater than the time limit during the learning cycle (because you generally take more time in the learning cycle than you would like during playback). However, if you want to delay the step after a specific step you can select this option, which will use the time that's recorded for that step ( say 12 seconds). If you haven't set a default time for this sequence then the 'Ignore Default Timer' naturally means nothing.

The handy thing about the Default Timer Limit is that you can set a maximum time without having to go back and change all the times because they're too slow.

3.3 What are the timing units, hours, mins, secs?

Answer: The timer is in hh:mm:ss

4.1 How do I position the mouse?

Answer: If you click on a control (say a button) you should see the mouse move to the location of the button when running the sequence. It only works for certain controls (tabs, lists, combos, fields, buttons, regions, options and check-boxes).

4.2 When I learn an 'AgentMove' step I often get the position wrong. Is there anyway to edit the co-ordinates that he moves to, to get the positioning accurate?

Answer: (see Changing a Step).

4.3 How do I open the Agent in a position other than the top left hand corner?

Answer: (see Setting the Opening Position of the Agent )

4.4 I tried to issue ds_SendPosition right after positioning the window, but to no avail. What am I doing wrong?

Answer: The agent is controlled by an OCX on a hidden window. The problem you may be experiencing is that the Agent window or another window (like the splashscreen) has the focus and not the window that you are calling the function from. Call settarget before doing the ds_SendPosition (and make sure that you're not omitting the parameters when calling ds_SendPosition).

5.1 Can I get SA to start working via a BUTTON on the MAIN procedure without having SA ?attached? to a menu item? If so how?

Answer: Yes you can.

1. You need to check the 'Disable "How Do I?" Menu' in the Agent local extension template on the frame.

2a. Go into the window editor of the frame and populate the 'Call Agent Browse Sequence' control template onto the toolbar.

2b. Place a button on the toolbar and handcode the necessary calls to the Agent DLL to display the sequences that can be run from the frame. Both 2a and 2b are demonstrated in the 3rdparty\examples\agent\sademo\sadabc.app example.

5.2 If I have a terminal client session open with the terminal server and I run my application in that session it does not see MsAgent.

Answer: Terminal Server creates a separate 'windows' directory for each client, so the Agent are all loaded in the default root directory, but it is looking for them in the client directory.

You basically need to copy the c:\WinNT\Msagent directory to the c:\WinNT\profiles\<UserName>\Windows\MsAgent directory. If you are using Windows 2000 the folder is: C:\Documents and Settings\<UserName>\Windows\MSAgent Directory.

5.3 Will you be able to run Special Agent if you distribute the agents.tps and gestures.tps to the client's machine and then run the agent on the local machine?

Answer: In the frame, Special Agent checks if you have a gestures.tps file and if there are any character details in it. If not, it warns you that if cannot find/invalid gestures file. This is because all the agents are stored with a ID code, and your sequence has the agent stored by that ID code. It can then build the gestures file making a database from the character files that it finds in the windows\msagent\chars directory - the problem is that all chars are not necessarily loaded in the same order that was in the initial gestures file, thus sequences learnt with Peedy may be played with Genie, etc.

If the chars in the gestures file are not found on the client's machine it simply ignores the specified agent and uses the default agent (by default it's Genie - but you can make it anything). If the default agent is not found, it picks the first in the list. If no chars are installed, it will warn you when you first load the program. Special Agent will be disabled if there are no characters found, but your program (with all normal functionality) will continue to run - although you will be unable to run any sequences.

Similarly, if there is no agent object ocx installed, you will be warned on startup and Special Agent will thereafter be disabled. You can disable the warnings (in the Global extension template) if you prefer.

5.4 Not all my sequence appear in the 'How do I?' menu. Is there a limit to the amount of sequences that appear in the 'How do I? menu?

Answer: There is a limit of 100, but what you're probably experiencing is one of two things:

1. Some of your sequences may have the 'Sub-Sequence' property checked on.
2. Some of your sequences may be attached to the wrong procedure (like a Splashscreen or hidden window). Ensure that the 'Start In' field is set to the frame.

5.5 None of my sequences appear on the 'How Do I?' menu.

Answer 1: Check that your sequences do not have the sub-sequence checked on (Changing a Sequence) and that the sequences that you require to start from menu have their first step in the window with the menu on it.

Answer 2: You may have a splash screen, and all the sequences are being started from there. You need to change the start procedure to the frame, you can do this in the (Changing a Sequence) window.

5.6 How should one use sub-sequences?

Answer: There is no real difference between a sub-sequence and a normal sequence apart from the appearance (or lack thereof) on the menu or on the pop-up when the Control Template Button is pressed. You can use sub-sequences and sequences as sub sequences (i.e. as insertions into other sub-sequences or sequences). For example, you could have a Grand Tour sequence which has only four lines, each of which calls another sequence or sub-sequence. You could then call the Grand Tour from a sub-sequence (because you may want to include some Agent activities which you don't want to include in the Grand Tour) so that the user can't run that sub-sequence from the "How Do I?" menu.

5.7 When I press CTRL-F12 the sequence window does not appear?

Answer: Steps to check:

1. Ensure that your application does use CTRL-F12 as the hotkey.
2. Delete the msa.ini file, which saves the previous position of the Sequence window. The window may have been moved off the screen on a previous occasion.
3. If still no success, continue with the steps in When I run my application there is no 'How Do I?' menu.

5.8 I've already used Ctrl-F12, what must I do now?

Answer: See Details on changing the Sequence Hot Key.

5.9 When I run my application there is no 'How Do I?' menu.

Answer: Steps to check:

1.Check that you have loaded the agent onto the PC where the application is being run from.
2.Check that the 'Place items directly on this menu' check box (How Do I Menu) is unchecked.
3.If you have set your program to use a variable for the Filenames, then you need to set the global variable for the file names before the call to the procedure ds_MsaFileNames - which occurs in the program Setup in your default module. In the global embeds - Program Setup - Priority < 1000.

5.10 I can't put Special Agent on the Help Menu. On the drop down list from which I choose, the Help Menu is not there. Other menus are there, and the Help items are there, but not the help menu.

Answer: You need to add a variable to your HelpMenu. Go into your window, into the menu editor, click on the help menu and enter a Use Variable (like '?HelpMenu').

6.1 My Sequence often GPFs my program and comes up with PUSHScope/POPScope errors, as well as 801 Bind errors.

Answer: Unfortunately there has been some binding problems in Clarion 5.5. It will be fixed in Clarion 6, and is non-existant in Clarion 5. As much of the binding as possible has been removed from Special Agent in version 1.41 to minimalize this effect, but this problem will still occur occasionally.

6.2 If the Agent does one of the gestures ending in 'ing' it does not do any other gestures, but continues doing that one. How do I get it to stop?

If a Gesture ends in 'ing' (or IDLE level 3) it is a continuous gesture. You will need to learn a 'Stop' gesture in order for any other Agent gestures to be played subsequently.

6.3 I would like to know when my sequence has finished running. What is the best way to find out?

Answer: The best way is use the ds_GetRunCheck() function. This will return a 0 when a sequence is not running.

6.4My sequences hang when I open one of my windows. The sequence stops and the agent 'falls asleep'.

Answer: It sounds like you have got a call to open your window in the middle of opening another window. When you open a window, while the window is initializing, the agent is put on standby.

There's a flag called AgentWait that gets set right at the top of your window. Once the window has finished opening, the flag is cleared, so that the Agent can continue with the sequence. This is to ensure that the procedure is in the 'Accept' loop before events are posted to it. If the procedure is not in the 'Accept' loop then the events that are posted to that procedure during window opening are 'lost'.

Thus it appears that the flag is being set, and then incremented in the new window's routine (the value is now 2), which is then decremented at the end of the second window's opening procedure (now 1). Special Agent is waiting for the AgentWait to be cleared before it can continue (which will only occur when the second window closes and the 1st window is allowed to continue it's opening routine). There are 3 possible solutions (ranging from best to worst):

1. Move the call to your 2nd window to the very first command in your ThisWindow.Init routine (i.e. before the ds_AgentWait() call).

2. Move the call to your 2nd window to after the opening is finished. In fact the call to clear the AgentWait flag is only in the event:OpenWindow. You will find a call to a routine called 'MsAAgentWaitSet'. You need to call your window after this call. For example:

of EVENT:OpenWindow
do MsAAgentWaitSet
SecondWindow

3. Place a call to clear and set the AgentWait flag before and after the call to your second window.

ds_AgentWait(-1,,,1)
SecondWindow
ds_AgentWait(1,,,1)

6.5 My menus don't always drop down in the sequence that I've learnt. What am I doing wrong?

Answer: Unfortunately Special Agent does not record menus dropping down (this is all handled by windows), it can only record the event that occurs when an item is accepted. During sequence playback, Special Agent presses a sequence of keys to drop down the menus and get to the item that was selected. You need to select an item in order for the menu to be displayed.

6.6 Sometimes my text does not input, is their something that I can do to change this?

Answer: You need to ensure that the EVENT:Accepted for the text that you've entered into a field is immediately preceded by a EVENT:Selected for that field. This means that you need to select that field and then type the changes to that field before you do anything else (like making the Agent gesture or speak).

6.7 When I run my sequence, I get an error message "Error getting thread for The Agent".

Answer: Check that your sequence opens The Microsoft Agent before issuing any commands to it, or check that the sequence calling the sub-sequence opens it. (See Errors)

6.8 I would like to run a sequence automatically when my program starts, how can I do this?

Answer: See Auto Running. Check out the example application (SADabc.app) that comes with the agent. I'll explain what I do in this example:

1. The Agent Extension Template on the frame contains the auto-run info ('Other Details' tab). I've put a variable in this field (AutoRunName).
2. I set the variable in the ThisWindow.Init method just before opening the window (on the frame). It reads from an ini file to determine whether the sequence must be run or not.
3. In the 'AboutDemoWindow' procedure, there's a check box that allows you to disable the auto-run sequence. I set the ini file in the ThisWindow.Kill method dependant on the state of the Run Sequence At Startup

Compile it and run this example to see the effect

6.9 The Agent does not always select the correct item in the menu and so I get sub-sequent errors because the window is not open.

Answer: You'll find that you have hidden, created or destroyed controls in your code, thus the menu mapping is incorrect for controls below or to the right of those that have been hidden, created or destroyed. There are 4 possible solutions (ranging from best to worst case) depending which will suite you the best.

1. Disable/enable controls rather than destroying/creating/hiding/unhiding controls.
2. Move the menus and items that are destroyed/created/hidden/unhidden to the right or below menus and items used in sequences.
3. Hand code the call to the menu mapping routine for each of the controls occurring to the right of the hidden menus like this:

Agent - Before EVENT:UserItem event handling

if ~MenuHidden

Agent - After EVENT:UserItem event handling

else
0{prop:active} = 1
if MenuHidden = 1
ds_ReceiveItemMap(MsAHotKey & 'RRRRDDE') !This is the key sequence to get to the item
!through it's parents
elsif MenuHidden = 2
ds_ReceiveItemMap(MsAHotKey & 'RRRDDE') !This is the key sequence to get to the item through it's parents
end
end

You can check the technical manual for more details on the ds_ReceiveItemMap, but briefly - an R means a RightKey stroke and a D means a DownKey stroke. Obviously the map for each item will be different. You must only have one E at the end of the map (for Enter). Create a variable called MenuHidden (for e.g.) and each time you destroy or hide a control, increment the variable. The easiest way to work out what the map is, is to run the program and press the actual keys to get to the menu item. Special Agent always presses the ESCKey after the MsAHotKey so as not to drop down the menus that are not needed. If you hide or destroy the route menu (i.e. the left most menu) you will need to reset the MsAHotKey.

4. On each item event that is learnt in a sequence, uncheck the "Item Event" check box. This will ignore item mapping (so you won't have the drop down menu effect). This will handle items like the way Special Agent used to do it before Version 1.16.

6.10 I am having problems with figuring out how to "Learn" opening menus, selecting tabs etc.

Answer: When you're in 'Learn' mode, the events that are generated in your program will be recorded and stored as a sequence. In other words you get into learn mode (CTRL-F12 and click the Learn button - the 'Learn Sequence' window should appear), and then you open the browses as normal, click buttons, enter text into fields, etc and whatever you do will be recorded. Click the 'NoLearn' button (crossed-out book) on the 'Learn Sequence' window to get out of LearnMode. When you run the sequence, it will be played back in the sequence that the events were recorded.

6.11 I have a sequence of ds_AgentDoGesture() and ds_ImmediateAgent() commands in sequence. Some of the ds_AgentDoGesture() commands are not being done, and the agent picture isn't refreshed (i.e. it leaves a picture trail). What am I doing wrong?

Answer: What's happening is that the ds_AgentDoGesture is skipped if the agent is busy (see Tech. Docs for more info). You need to put the ds_AgentDoGesture() command in a loop and then refresh the window once the ds_AgentDoGesture() command is completed. For example:

DS_IMMEDIATEAGENT('MERLIN','Hi')
loop until ~band(DS_AGENTDOGESTURE('Alert'),1h) ; yield() .
DS_IMMEDIATEAGENT('MERLIN','Hi')
loop until ~band(DS_AGENTDOGESTURE('Announce'),1h) ; yield() .
ThisWindow.Reset(1) !do refreshwindow for legacy This does away with the agent gesture trail
DS_IMMEDIATEAGENT('MERLIN','Hi')
loop until ~band(DS_AGENTDOGESTURE('Blink'),1h) ; yield() .
ThisWindow.Reset(1)
DS_IMMEDIATEAGENT('MERLIN','Hi')
loop until ~band(DS_AGENTDOGESTURE('Confused'),1h) ; yield() .

7.1 I bought Special Agent some time ago - for Clarion 5 - but I now need the version for Clarion 5.5 (or later). How much does it cost, and where can I get it?

Answer: Updates are free, and can be downloaded from the web site - www.capesoft.com - the password is issued to you when you register.

7.2 So how do I register?

Answer: Send us your contact details, via email (sales@capesoft.com) or via fax (+27 21 715 2535). Include the dealer you bought it from and the order number.

Technical Documentation

The technical documentation for Special Agent is available in a separate document entitled Technical Documentation.

Removing Special Agent from your application

You will need to delete the Special Agent global template from your application. You must then exit the application and re-enter again. You may need to compile a few times, because each time the compiler gets to a procedure that has used an Agent code template it generates an error before removing the code template.

It is important to note that when you remove Special Agent from your application, all your settings may be lost. A more advisable option is to check the 'No Agent' check box in the global template, which will not generate any Agent code into the application when it is compiled.

Copyright and License

This product, and all the files contained therein, is copyrighted © 2003 by CapeSoft Software (Pty) Ltd. You are licensed to distribute any of the DLL's contained in this package with your applications. You are not allowed to copy any of the other files, including but not limited to, Template (TPL) files, Library (LIB) files, Resource (RSC) files and documentation files.

CapeSoft Software (Pty) Ltd, employees of CapeSoft Software (Pty) Ltd, and Dealers of CapeSoft Software (Pty) Ltd products, explicitly accept no liability for any loss or damages which occur from using this package. Use of this package constitutes agreement with this license. This package is used entirely at your own risk.

Acknowledgements

Thanks to all supporters and critics of Special Agent for the e-mails. Your suggestions and recommendations have been extremely valuable to the shaping and growth of this product.

A special thanks to James Fortune and John Maguire for all your helpful input.

Where can you get it?

The full working version of Special Agent is available at $199 from:

CapeSoft Sales
	Web	www.capesoft.com
	Email	sales@capesoft.com
	Telephone	+27 21 715 4000
	Fax	+27 21 715 2535
	Post	PO Box 511, Plumstead, 7801, South Africa

Buy Online
	Web	www.clarionshop.com

CapeSoft Support
	Email	support@capesoft.com
	Telephone	+27 21 715 4000
	Fax	+27 21 715 2535
	Post	PO Box 511, Plumstead, 7801, South Africa

Version History

Version History for Version 1.45 - Released 24 October 2003

Fixed Template Regression (for C5 and C55) introduced in verrsion 1.44.

Version History for Version 1.44 - Released 18 September 2003

Clarion6 compatible build - not extensively tested, and there seem to be some delay issues (with thread swapping) so not recommended for shipping with Agent activated. Recommend disabling Special Agent for c6 applications. This should not affect C55 and C5 versions.

Version History for Version 1.43 - Released 3 April 2003

DLL Fix - Fixed the selector on the Sequence list box.
Added feature to the ds_StopSequence function. You can stop the sequence immediately (without waiting for the Agent to complete it's task).
Template Fix - Lib not included in the project if Agent is disabled in this application.

Version History for Version 1.42 - Released 4 October 2002

DLL Fix - Fixed the resizing of the screen controls in the Learn Sequence window and added a 'Do' and a 'Say' button to aid in agent interface.
Examples Fix - Updated examples to ship with new graphics.

Version History for Version 1.41 - Released 11 June 2002

DLL Change - attempt to minimize C5.5 BIND problem by removing as many PUSHBIND/POPBind pairs as possible (RunSequence, ItemHandler, ds_TheAgent, ds_NewAgentThread (if already open))
DLL Change - Was not deleting controls from the Control Q upon exit from procedures - so duplicates could occur.
DLL Change - Protection for PosFetch - when obtaining the position of a window - if the event gets 'lost' - reposted (PosFetch contains the thread value of the window required).
DLL Change - Aborts running the sequence if the event cannot be posted. PostSequenceEvent changed to funciton - returns a 1 if failed.
DLL Change - API function to bring window to the top when an event is posted to it (if it does not already have the focus). Event used is event:UserPosition.
TPL Change - Don't show options in DLL templates that pertain to EXEs only.
Install Fix - included gifs in install set.
DLL Change - FilePath added to No Agents loaded message to inform users of where the OCX is expecting the Agents (Microsoft Terminal Client support).

Version History for Version 1.40 - Released 17 May 2002

Install fix - Included icons for the examples in the install set.
DLL Change - Fixed screen flash for Agent windows when running a sequence.
DLL Change - stabilised sequences when run on XP (Deleted list on Agent window, protect Timer event in RunSequence window)

Version History for Version 1.39 - Released 25 April 2002

DLL Change - Fixed bug in ds_ImmediateSay - new agent OCX don't have unique start event.
DLL & TPL Change - New feature: allows Balloon to be hidden, while just audio occurs.

Version History for Version 1.38 - Released 5 March 2002

DLL & TPL Change - Allows Idle mode off.
Tpl Change - Allows the Agent Settings to be defaulted in the Global Template for each application. Done through a new function: ds_SetAgentOptions().Allows settings overriding and specification of the filename.

Version History for Version 1.37 - Released 23 January 2002

DLL Change & TPL Change - Allows disabling the Agent settings in the agent popup menu. (new function to set variables and code template to call function).
DLL Change & TPL Change - Allows no learning of user specified/move events. Events to be ignored are stored in a file (setting in the Global Extension Template) and the file is editted from the Sequence Window.
DLL Change - If gestures file must not be created, give abort option (which deletes the gestures file on the way out).

Version History for Version 1.36 - Released 08 October 2001

DLL Change - All relevant AgentWait changes made in the ds_AgentWait procedure.
DLL Change - Win2K does not post all events to the OCX control. Now caters for no Start Event (1).

Version History for Version 1.35 - Released 10 August 2001

TPL fix - fixed multi-proj support
DLL change - increased string size (255 to 2048) for popup (Popup that appears on the select sequence template)
DLL change - allows complete disable of Special Agent (in ds_MsAFileNames function or Code Template).
DLL Change - Access to the Agent Properties Screen, and more settings (Keep bubble open, Text shown immediately). Right click the agent during run-mode (details).
DLL Change - Checks in some of the newer functions to return if Special Agent is disabled at runtime, or there are no filenames loaded. Prevents GPFs in some of the functions (that use the agent files) if the filenames aren't specified.

Version History for Version 1.32 - Released 9 May 2001

Tpl change - Checkbox entry (change() instead of display()) - support for Capesoft MessageBox
DLL change - ds_GetRunString
DLL change - ds_SetPosition
DLL change - ds_AgentWait: increments/decrements AgentWait instead of setting it - support for Capesoft MessageBox
TPL change - Global Extension Sheet changed:1. in EXE set error handling (multi-DLL), 2. check for multi-DLL apps changed
DLL change - ds_AgentDoGesture. Opens agent if not open already. Optional parameter allows you to select the agent to appear
Tpl change - fix Multi-Proj support
DLL change - prevent empty say commands
DLL change - Handle Event:AlertKey properly (especially in relation-Trees)
Tpl change - support toolbar buttons

Version History for Version 1.31 - Released 23 February 2001

Doc change - error message documentation updated
Tpl change - support for multi-proj
DLL change - prevent 'Hide' popup menu with right click from occuring
Bug Fix in TPL - supports toolbar buttons (was trying to run a sequence when toolbar button was pressed)
New Function - ds_GetAgentStatus returns the current agent open, it's busy status and the thread of the window controlling the agent
New Function - ds_AgentDoGesture does the required gesture if the agent is open (similar to what ds_ImmediateAgent does for speech)
Tpl change - allows controls to be disabled from recording events to a sequence (existing events in sequences will still be run)
Changed the way the template inserts the MsATakeEventinto the procedure.

Version History for Version 1.30 - Released 18 January 2001

Doc and tpl change - Explained Agent_CallASequence template
Bug fix in tpl - GPFs when closing a multi-DLL legacy App

Version History for Version 1.29 - Released 14 Decemeber 2000

Bug Fix - occasional GPF in close window
Bug in C55 - Mouse Move not working, worked around real to short compare.

Version History for Version 1.28 - Released 15 November 2000

Bug Fix - fixed compile problem in C55 for local-mode compiles.

Version History for Version 1.27 - Released November 1, 2000

Bug Fix - All Applications check box in the Sequence select window
Bug Fix - Force Voices/Language selections when invalid to 0 (for old sequences)
Bug Fix - Default Agent gesture time-out too short so causing problems for long gestures
TPL Fix - Code TPL for changing the language fixed to include changing the 'How do I?' menu
Bug Fix - All DLL windows translated (Voices, Languages, etc. were missed out in v1.26)
Docs revamped and explain example apps
Added to TPL - can change 'How Do I..' menu name (for translation purposes)

Version History for Version 1.26 - Released September 15, 2000

New function ds_GetAvailableAgents to check if agent is available, and to select an agent from a popup list. (see the Code Template)
Bug Fix - ds_ImmediateAgent calls selected Agent (bug introduced in 1.25)
Translation added. Translate DLL windows and Error messages in an ini-type file. (see International Support).
Template modified for INTL support. Allows filesetup and %ProgramSetup code in EXE only.
Prevents Sequence Window, ImmediateAgent and Sequence popup menus from appearing if no agents/no agent OCX loaded.
Limit sequences to the selected language. (see Sequence Selection Limiter)
Functionality added to change the agent voice. (see Changing the Agent's voice)
Correction for names that appear in the 3rd party agent list. Obtains fullname instead of shortname (i.e. DoctorMike instead of Doctor~1)

Version History for Version 1.25 - Released August 9, 2000

Support for 3rd Party agents. (see Using 3rd Party Agents)
Bug Fix - GPF fix in learn moves (file handling out of OCXEvent routine to procedure)
Show agent in a specified position (first move after Show is recorded as the ShowAt position) (see Showing Agent Elsewhere)
If unknown gesture is issued to Agent, continues with next gesture
Optionally display error message when unknown gesture is posted (setting on Sequence Window, stored in ini file for Dev use). (see Warn on Unknown Gesture)
Optional (set in Global Template) Error Messages if no Agents or no Agent OCX loaded. (see Don't display Agent load errors)
Only issue stop if Agent in continuous gesture, else Stop gesture ignored
Removed "Remake Gestures" item from the sequence window's "View" menu

Version History for Version 1.24 - Released July 31, 2000

TPL fix - Export AgentRemainOpen variable for multi-DLL applications
Updates by popup in the Sequence Window (and hotkeys)
Learn window is set to resizable so that larger text entry fields can be viewed
"Ignore Default Timer" check box fixed to hide/unhide Timer field correctly
Timer EIP removed in the Sequence Window
Setcursor to wait during agent open in learn mode - helps prevent the GPF when the IMM attribute is on
Bug Fix - GPF on window/agent moves in IMM windows
Learns only 1 move when an IMM window is moved
Template generated Source cleaned up and moved (where possible) to the DLL
Bug Fix - Check box action (in legacy) works

Version History for Version 1.23 - Released June 2, 2000

Bug Fix - occasional GPF in move command
Bug Fix - moves learnt sometimes learns (2;2) co-ordinates
Bug Fix - in change event window, event co-ordinates when negative are not displayed correctly
Add auto-IMM attribute check box in global extension template set. Forces IMM attribute on windows if checked, embed added to local extension template for handling sizing/moving windows which cannot have the IMM attribute

Version History for Version 1.22 - Released May 17, 2000

When learn button pressed on last event, add steps to the bottom of the sequence, instead of inserting
Added 'Delete' and 'Maintain Sequence' items to the Sequence menu of the Sequence window
Print button on the SelectSequence window moved off tab to window
Print button added to the Sequence window
Item and menu messages and tips corrected
Call to HTML docs added on the Sequence window
Added error message to TPL when no variable is used for a check box
Get correct agent after running a sequence with a sub-sequence call at the end
Correction in continuous gesture after say command to allow stop gesture
Updated HTM docs (Acknowledgements, C55)
Bug Fix - If seq starts with call to sub-sequence, ran from previous sequence
Bug Fix - Could not add call when no other events existed in the sequence

Version History for Version 1.21 - Released March 16, 2000

Supports Clarion 5.5
Text Entry improved - entered from DLL
Fix for contracted in Relation tree structures

Version History for Version 1.20 - Released February 22, 2000

Template support for CPCS' Report template
Eliminate infinite wait after Agent move error
Default 'Omit the Agent from this procedure' to true for all Report, Process and Source templates. Also disabled for these
Enable All & Disable All buttons added to the Gesture select screen
Remove Number from Item Message in the 'How Do I' menu
Change Agent event after Say to end speaking rather than Balloon Close - makes the sequences flow better
Index to FAQ and tech docs added
Template change to compact generated code. EVENT:UserSelect handled outside the case field statement
Immediate Move option to allow instant change in position for an Agent move
ds_AgentSetWait variable added to local template so as to monitor the calling of ds_AgentWait - prevents AgentWait from remaining set if the ProcedureReturn is executed before the AgentWait is cleared
Sequence file is used directly instead of loading the file to a queue and working on the queue. All editing, etc. is done directly on the sequence file. As a result, some functions are slightly slower, but far more robust
Text entry is made more robust with checks that the window is in focus so that text is entered into the control with focus and not to another window
Upgraded Docs - FAQ contents table with Hyperlinks, makes using the FAQ easier
Supports Expanding and contracting of Tree structures in a list box
Fix for mixed upper and lower case application and procedure names (which can change with a different operating systems)
New sequences will use lower case only. A procedure is added to convert the old sequences to only use lower case procedure and application names.

Version History for Version 1.19 - Released November 8, 1999

Fix to prevent no agent EXEs that use agent DLLs from crashing on file open because no file name loaded
Option to post Agent run-time errors back to the exe so that they can be handled by the exe
Fix the cancel insert sequence
Move the Sequence Properties to the Sequence menu in the Sequence window
Add checkbox in the frame template to disable the 'How Do I?' menu
Option (in global template) to keep Agent open when sequence finished running
Gesture file created. In the sequences window there is a menu item 'Gestures' where all the available gestures can be enabled/disabled
'Remake Gestures' in the sequences window menu is an item to remake the gestures file to restore the default gestures

Version History for Version 1.18 (Template change only) - Released August 17, 1999

Move the function ds_MsAFileNames() to the Global template (in the Program Setup).
Allows the user to set the file name in the Global Extension if the application is a multi-DLL application where the Global Data is defined in another DLL.

Version History for Version 1.17 - Released August 5, 1999

Hide/unhide Default Timer according to use
Load default timer after initial learn
Add Sequence properties item to the menu to view the sequence properties straight from the sequence window
Fixed Agent moves (was referenced to incorrect window after closed before next event from new window saved)
Fixed Mouse moves (occasional moves missed)
Added Cancel button in BeginningorEnd window (used before running/learning a sequence)
Fixed NewSelection for Option control in Legacy
Column in Sequence window changed to XDelay (Extra Delay). Normally shows a 0, else if Ignore Default Timer, then shows delay time. Edit-in-place still available
Auto-set Ignore Default Timer when Delay changed in Sequence Window
Changed default sequence file name to 'Agent.tps' (NB for users upgrading from version 1.16, but irrelevant for prior users)
Changed look of the Learn window, no 'Say' and 'Do' buttons. Press the enter key when you require to gesture or say (depending on which field is selected)

Version History for Version 1.16 - Released July 15, 1999

New Feature: Drop down menus during running sequences. If you would like your previous sequences to drop the menus down then you need to indicate which steps pertain to items (see Control is an Item)
Event from Agent to post next event changed to 25 (Close Speech bubble event after say) and 11 (after startagent)
Updated ds_AddEvent to ds_AddEvent1 procedure to optimize generated code
Added a sequence report to print out a sequence
Added the REQ attribute to the Agent_JustSay code template's text field
Stabilised Save routine - escape route from infinite loop (in auto-renumber) and stabilized auto-renumber
Allowed a change in name for the sequence file (set in the global extension). It is important (for Version 1.16 users) that you either change the file name of your 'Agent.tps' to 'Agent.csa' or enter 'Agent.tps' into the file name field in the global extension (see Sequence File Name)
Deleted Agent selection from the global extension template

Version History for Version 1.15 - Released July 1, 1999

Special Agent moves learnt and played back with respect to the current window font and the frame font proportionally
Speech output tags enabled (see Useful Agent Speech Tips)

Version History for Version 1.14 - Released June 8, 1999

"Save As" fixed - loads saved sequence instead of the previous sequence
Displays correct name on the sequence window
Steps the highlighted step, not the previous step
Included auto-conversion of the data file changes made in ver 1.13

Version History for Version 1.13 - Released June 4, 1999

Fixed AutoLoad bug - ini setting is not overwritten
Fixed Learn Beginning|Previous|End Window and it shows counter not steps
Procedure name string fixed (two variables in DLL limit it to 40 chars) - now 120 chars max

Version History for Version 1.12 - Released June 3, 1999

Included menu template into local template (Agent.tpl)
Added AutoLoad option to Options menu on the Sequences window. Auto-Load is for loading the last sequence that was edited when the Sequence window is run
Added tab containing all sequences in Agent.tps file to the Select Sequence window
Fixed drops - undrops the list after new selection is accepted
Added Start in procedure and application fields on the Update Sequence details window
Stops all Agent animations when the Agent is double-clicked
Displays current sequence that is loaded in the title bar of the Sequence window
Auto-Renumber of a sequence if there is an error saving it

Version History for Version 1.11 - Released May 27, 1999

Fixed saving of file from auto load-up
Fixed compile in local mode (template change and include c5olexl.lib into the c5msaxl.prj)
Fixed export of Hot-key in multi-DLL mode
Fixed Text box entry
Added LastEdit file to the dictionary - contains the last edited sequence information instead of in an ini file

Version History for Version 1.1 - Released May 20, 1999

Fixed BeginningorEnd window from popping up during sequence run
Drop combos fixed in ABC and legacy
Fixed timer default (takes individual time unless > default time)
Fixed double click on sequence window. Only goes to form if List db-clicked
Added autoblink after say to delay allow the agent to finish saying before next event
Fixed mouse movements
Fixed the tab sequence in the "Changing Sequence Details" form
Fixed the Agent Position hide in the "Changing a step's details" form
Added ds_ImmediateAgent to replace ds_ImmediateGenie. Will now perform immediate say with agent specified

Version History for Version 1.07 - Released May 14, 1999

File required Agent.tps (not just Agent) in dictionary
Default Timer for each sequence, with override available for each event
Column Resizing saved for sequence window
Restore defaults column sizes menu item added
Changed window after learning new sequence to UpdateSequence window
Autoload last sequence that was worked on
Quick load of last 6 sequences that were worked on - app dependant
Select agent when you open the agent (popup menu) (Learn Sequence screen)
Add last attrib to DLL Global mappings in TPL
Fix menu item call to sequence
Drop Lists fixed in ABC
Text entry modified

Version History for Version 1.06 - Released April 15, 1999

Put delay in after Closing the Agent at the end of a Sequence
When double click Agent, pause automatically, with option to continue or stop
Locate '+' button on sequence window correctly, immediately
Display name of file on the sequence window
Hide Default timer options until implemented (From Sequence form and Step form)

Version History for Version 1.05 - Released April 14, 1999

Fixed Double click on the Sequence window to change step
Fixed in EIP for timer (not working properly)
Justified Event Comment and Value on the Sequence window
Locate '+' button on sequence window correctly
Drop-down list for Agent select
Default agent in new sequence to the default one
Resize drop-down list box for gestures
After say return to say field
Change to loaded agent if the learnt one is not loaded
Fix pause bug when another agent is used when running
Begin override timer function - to be completed in version 1.0
Code template to call a sequence

Version History for Version 1.04 - Released April 14, 1999

Code template to call a specific sequence
Sequence Window resizing immediately
Agent Check bug - check reflects correct status of the Agent
Pop window up to select here/beginning/previous when running
Fixed Agent moves
Restore default Agent when starting a new sequence
Hide controls after fail in select sequence
Hide renumber item when sequence queue is clear
Put in EIP for timer
Agent gestures back in alphabetical order

Version History for Version 1.03 - Released April 12, 1999

Agent moving - store in dialog units, solves moving problem for different screen settings
Popup menu at double click genie to pause/stop the sequence at runtime
Assign CtrlF12 to be an option on the global extension template
Sequence window resizable
EIP removed
Window to prompt user for saving on exit
Allow user to select a character for a sequence
Make provision in the .dct for two fields for the Agent speech - one to say and one to show
Renumber item on the menu - allows sequence to be renumbered
ImmediateSay command closed when speech bubble close event is received
Bug - Sequence won't finish until the Agent has completed what he's doing

Version History for Version 1.02 - Released March 16, 1999

Tab swapping - browse refreshes in legacy
Options - selects the desired option in legacy
Agent events - use 11 for all except start (1) and end (3)
No edit-in-place on the Sequence Window Value
Auto close when sequence stopped/ sequence window closed
First Agent move in new window fixed to correct reference
Version control in DLL
Autorun in AgentMenu template
Add-Call added before the highlighted step
Agent Say nothing prevents run freeze

Version History for Version 1.01 - Released March 5, 1999

When moving MDI child windows takes the moved to co-ordinates
References each control by name and not by ID
Timing of genie events all set to 500 msec to prevent any delays
Step comments to show agent, not genie

Version 1.00 - Released February 26, 1999

[End of document]

meatloaf@capesoft.co