


	Version www.capesoft.com Updated 25 February 2003

Technical Documentation

See also the Complete Documentation

Available Functions
		ds_SetAgentOptions [Updated in Version 1.39]
		ds_DisablePopupOptions [New in Version 1.37]
		ds_AgentDoGesture [New in Version 1.31]
		ds_GetAgentStatus [New in Version 1.31]
		ds_GetAvailableAgents
		ds_MsALanguage
		ds_GetSetLanguage
		ds_ChangeAgentVoice
		ds_StopSequence
		ds_MsAErrorCheck
		ds_GetLearning
		Ds_GetRunCheck
		Ds_ImmediateAgent
		Ds_ImmediateGenie
		ds_AgentInterface
		ds_CheckFunction
		ds_SetMousePos
		ds_AgentWait
		ds_RecieveItemMap
		ds_MsAFileNames [Important Changes in Version 1.35]
		ds_SendPosition
		Functions not Available for General Use

ds_SetAgentOptions(string ProgramName,<long PaceBalloonText>,<long CloseBalloon>,<long AllowIdling>,<long OtherFeatures>,long options=0,<string IniFile>)

This procedure is used to set the default settings for the agent's behaviour. If the settings are already there, then they are not altered. The settings are simply default settings (unless you set the Options bit to override the existing settings).

Parameters:

(string ProgramName,<long PaceBalloonText>,<long CloseBalloon>,<long AllowIdling>,<long reserved>,long options=0,<string IniFile>)

ProgramName:	The name of the current application (the template variable %Application should be used)
PaceBalloonText:	Set to pace the balloon text with the speech, cleared to show all the text immediately.
CloseBalloon:	Set to close the balloon when the agent has finished speaking the text in the speach bubble.
AllowIdling:	Set to allow idle mode on
Other Features:	Bit0: Set to show the speech balloon, and cleared to hide the balloon.
Options :	Bit0 - if set will make the defaults program specific, rather than using the general settings. Bit1 - if set will override the existing values found in the IniFile.
IniFile:	the name of the Ini file to store the settings (if omitted, it defaults to 'msa.ini').

Returns:

Nothing

ds_DisablePopupOptions(byte NoChangeVoice=0,byte NoAgentSettings=0,<long options>)

This function is used to enable/disable the Agent some of the items (that pertain to the agent settings) on the Agent's popup menu (which appears when you double click the agent while a sequence is running).

Parameters:

(byte NoChangeVoice=0,byte NoAgentSettings=0,<long options>)

NoChangeVoice:	Disable/enable the Change Voice item in the popup menu.
NoAgentSettings:	Disable/enable the Agent Settings sub menu in the agent's popup menu.

Returns:

Nothing

ds_AgentDoGesture(DoGesture string,<AgentNow string>),long,proc

This function is used to command an open agent to perform a gesture (outside a sequence). If there are no agents open, then the default agent (or that agent specified in the AgentNow parameter) will be opened before the gesture is performed. If you want to close the agent, then set the DoGesture parameter to 'CloseAgent'.

Parameters:

(DoGesture string,<AgentNow string>)

DoGesture:	The gesture that the agent must perform. If this is not a valid gesture for this agent, then the agent will not perform the gesture.
AgentNow:	Optional parameter. This allows you to specify the agent to use, if there are no agents open.

Returns:

A long containing:

0 if the command was issued successfully, whether the gesture was performed or not (the gesture may have been invalid for this agent).
1 if there is an agent open, but the agent is currently busy performing an action. No command issued.
2 if the agent is not open. No command issued.
4 if there is currently a sequence running. No command issued.
8 if there is currently a sequence being learnt. No command issued.

Thus if a 5 is returned, then there is a sequence running and the agent that is open is busy performing an action.

ds_GetAgentStatus(),string

This function is used to determine some info on the current Agent status. You can use the return to determine whether there is an Agent currently open, which agent is open and whether the agent is presently performing an action.

Parameters:

None

Returns:

A Group of the following structure:

ReturnGroup	group,pre(RG)
UseThisAgent	string(20)	!The Agent's name that is currently open. Clear if no Agent is open.
AgentBusy	long	!Set if the Agent is currently performing and action (Say/Move/Gesture/Open/Close). Clear if the Agent is idle.
AgentThread	long	!The Thread of the window that controls the Agent. Clear if there is no agent open.
ExtraLong	long	!Reserved
ExtraStr	string(40)	!Reserved
	end

ds_GetAvailableAgents(<string>,<long>,<string>),string

This Function can be used for a number things:

1. It can be used to test if a specific agent is available
2. It can be used to return a list of all the agents in the Special Agent 'Characters file'. The list is a | (vertical bar) delimited string of the agents.
3. If can be used to popup a list of all the agents and then return the user's selection from this list.

Parameters:

(TestAgent,Options,ExtraS)

TestAgent:	Indicate a character name to test if this Agent is loaded
Options:	bit0 (LSB) if set indicates that the agents in the file but not loaded should be preceded with a '~' in the \| delimited string. bit1 if set indicates that the function should display a popup menu of the \| delimited string and return the name of the agent selected.
ExtraS:	Reserved for later use

Returns:

1. If TestAgent is not omitted then a '1' is returned if the Agent requested is present, else a blank '' is returned.
2. If TestAgent is omitted and Options is omitted or bit1 of Options is clear (i.e. 0), then a | (Horizontal bar) delimited string list of characters is returned.
3. If TestAgent is omitted and Options bit1 is set, then the agent's name selected from the popup will be returned.

ds_MsALanguage(string,<long>)

This procedure is used to set the translation file to use for translating the Special Agent windows and messages. You can optionally set the language (if it is contained in the translation file) for the Sequence limiting (i.e. How Do I? menus, etc.).

Parameters:

(Lang,Options)

Lang:	The translation file to use for translating the Special Agent windows and messages.
Options:	bit0 if set, then get the language setting in the translation file, and if existant, then set the Sequence Selection Limiter to this language (this language must be matched precisely in the Special Agent languages file in order to be able to do this).

Returns:

Nothing.

ds_GetSetLanguage (<long>,<string>,<long>),string,proc

This function (or procedure) is used to set or get the Sequence Selection Limiter language in order to limit the sequences that are displayed in the 'How do I?' and sequence popup menus.

Parameters:

(SetLanguageNo,SetLanguage,Options)

SetLanguageNo:	set the Sequence Selection Limiter directly. If a 0 is passed, then the Sequence Selection Limiter will be cleared and all sequences will be displayed in the 'How do I?' menu and sequence popup menu.
SetLanguage:	if SetLanguageNo is omitted then the Sequence Selection Limiter will be set by the SetLanguage string. This language must be matched precisely in the Special Agent languages file in order to be able to do this.
Options:	reserved for later use.

If all parameters are omitted then the language is set to that in the agent ini file ('msa.ini').

Returns:

The Language that the Sequence Selection Limiter has been set to or 'OK' if the Language setting is cleared. If there was an error obtaining the language from the Special Agent's Language file, then an empty string is returned.

ds_ChangeAgentVoice (<string>,<long>,<long>),long,proc

This function (or procedure) is used to set the current agent's voice to an alternative one. The available voices (from the Special Agent Voices file) appear in a popup menu and allow the user to select one from the queue. This voice selection will be stored in the agent ini file ('msa.ini') and will be used whenever that agent is used.

Parameters:

(AgentName,AgentNo,Options)

AgentName:	The name of the Agent whose voice must be set.
AgentNo:	The reference number for the agent (in the Special Agent Characters file) whose voice must be set (if AgentName omitted). If both parameters are omitted then the current agent's settings will be used
Options:	reserved for later use.

Returns:

The choice from the popup menu: 0 if nothing is selected, 1 if the Default is restored (this will only be activated the next time the agent is opened if the required agent is currently open), the voice selected from the popup.

ds_SetLanguagePath (<string>,<string>,<long>,<string>)

This procedure is used to set the path where the language files are kept. It can also be used to set the language file to be used for translating the windows.

Parameters:

(lfile,lpath,options,X1)

Lfile:	The default translation file to use. Can be changed with the ds_MsALanguage function.
Lpath:	The translation file path (where all the translation files are stored). This is not reset in the ds_MsALanguage function.
Options:	bit0: (LSB) set to enable all translatings. bit1: set to check all Special Agent messages are in the translation file. Will do the checking the next time the function ds_CheckFunction is called (tempate use only).

Returns:

Nothing.

ds_StopSequence(<long>),long,proc

This function is used to stop a sequence that is currently running. Sets the DLL out of run mode. If the 'Keep Agent open after running sequence' check box in the Global Extension Template is clicked on, then the Agent will not automatically close (unless bit0 of the Options parameter is set). You will need to run a sequence with a 'CloseAgent' command in it in order to close the Agent.

Parameters:

(Options)

Options:

A bit loaded flag: bit0 - Stop Immediately (agent and sequence)

Returns:

A long, which is a -1 if the ds_StopSequence fails and a 0 if it passes. If the DLL is not in run-mode then it will return a -1.

ds_MsAErrorCheck(),Group

This function is used to retrieve the error parameters for the last error that was generated while running a sequence. Calling the function will clear the error parameters in the DLL. This function must be called as soon after the error was generated as possible, because if another error occurs before this function is called the previous error parameters will be overwritten by the new error parameters. When the 'Don't display error messages' check box in the global extension template is checked, a group called MsAErrorGroup(PRE=MAEG) will be added to the local data of the frame, which you can use to receive the return of this function. Note: this function is automatically called and the group automatically populated when the above checkbox is checked - you will find it in the source after the EVENT:UserError handling in the frame procedure. There are two embed points that you can use to enter code to handle the errors. They are: 'Agent - Error Event Handling' and 'Agent - Error Event Handling (After Generated Code)'.

Parameters:

None

Returns:

A group (255 characters) made up of the following:

-A byte, (MAEG:On) which indicates whether the 'Don't Display Error Message' flag is on or off. (1 byte)
-A long, (MAEG:Code) which is the error code of the error generated (see Special Agent Complete Documentation). (4 Bytes)
-A string, (MAEG:Name) which is the error name (46 Bytes)
-A long, (MAEG:Thread) which is the thread value (if any) where the error occurred. (4 Bytes)
-A string, (MAEG:Desc) which is a full description of the error (normally the message displayed when the error occurs). (200 Bytes)

ds_GetLearning(),long

This function is used to determine whether your program is in learning mode or not. It does not change any settings in the DLL.

Parameters:

None

Returns:

A long, which is a 1 if the DLL is in Learn mode or a 0 if not.

Ds_GetRunCheck(),long

This function is used to determine whether your program is running a sequence or not. It does not change any settings in the DLL, although if the DLL is in the middle of a step (in StepMode) the DLL will be informed of a StepCompleted.

Parameters:

None

Returns:

A long, which is a 1 if the DLL is in Run mode or a 0 if not.

Ds_ImmediateAgent(string,string),long

This function will make the agent appear immediately (without the normal show action), say the string that is passed to it, and then disappear immediately (without the normal hide action). This action can only be used outside of running and learning modes, i.e. it is independent of sequences.

Parameters:

(Agent,Sentence)

Agent:	the first string passed is used to determine which agent should be used to perform the function.
Sentence:	a string containing a valid sentence, which will be issued for the agent to speak. Note: There should be no illegal speak characters. See the Agent docs under Learning A Sequence.

Returns:

You are not required to call this as a function, i.e. you may call it as a procedure.

A long, which returns a 1 if the request is completed, a 2 if there is no text passed to it, a 3 if the DLL is in Learn or Run mode, and a 0 for an unknown error (e.g. Agent timed out).

Ds_ImmediateGenie(string),long

This is an old function retained for compatibility purposes. This function will make the Genie appear immediately (without the normal show action), say the string that is passed to it, and then disappear immediately (without the normal hide action). This action can only be used outside of running and learning modes, i.e. it is independent of sequences.

Parameters:

(Sentence)

Sentence:

a string containing a valid sentence, which will be issued for the agent to speak. Note: There should be no illegal speak characters. See the Agent docs under Learning A Sequence.

ds_AgentInterface(long,<string>,<string>,long,<string>)

This procedure calls the sequence window and (depending on the parameters that are passed) will run a sequence automatically, or bring up a popup menu displaying a list of available sequences to run.

Parameters:

(Controls,Proc1,app1,Options,SeqName)

Controls:	This is basically used to tell the procedure what you want it to do. If this is a 0 then the Sequence Window will appear (like with the Ctrl-F12 hot key). For all other values the Sequence Window will not appear. If this is a 1 then and there is no SeqName, then a popup menu will appear at the position of the mouse giving a list of the sequences to run. If the value is <AgenttoWhere> (which is defined in the template) then a Select window will appear containing all the sequences that pertain to the App1 and the Proc1 that are passed as parameters (or the current Application and Procedure if they are omitted). For any other value, the sequence with that ID (or index) will be run.
Proc1:	<optional> This indicates the current procedure and will indicate which sequences can be run (dependent on Controls).
App1:	<optional> This indicates the current application and will indicate which sequences can be run (dependent on Controls).
Options:	Bit 1 indicates whether this procedure is a frame (set) or not (not set). This is important as it is used to set the reference co-ordinates of the program (if the procedure is the frame).
SeqName:	<optional> This indicates the sequence to be run by the sequence name. Controls need to be set to 1.

Returns:

Nothing.

ds_CheckFunction(string,string,<long>),long

This function is used to check the availability of an agent or agents. It is always the first function that is called when the program is fired up. In version 1.14, the file conversion utility is built into this function. The old sequence-step data file is converted into the new format.

Parameters:

(Agent,Pic,Option)

Agent:	This is the ProgID of the Agent. (Typically 'Agent.Control.2')
Pic:	This is the description of the Agent. (Typically 'Genie'). From Version 1.16 this is not required (from the DLL point of view) but is retained for backward compatiblilty.
Option:	not used at this stage.

Returns:

A long. If the Agent specified is found, then a 99 is returned, else a 0 is returned is no agent is loaded.

ds_SetMousePos(<long>,<long>,<long>)

This procedure will set the position of the mouse (or Agent) relative to the frame and the MDI window that is currently open. You can also use this function to do a relative move (of the mouse) to its previous position.

Parameters:

(x,y,f)

X:	The x position to move the mouse/ agent to.
Y:	The y position to move the mouse/ agent to.
F:	A flag to set whether the mouse moves relative to its previous position (1) or relative to the top left corner of the window focus (0). If the flag is set to 64 then the move pertains to the Agent and not the mouse.

Returns:

Nothing

ds_AgentWait (long,<string>,<string>,<long>)

This is a procedure that will stop the events from being posted from the Special Agent DLL to your program during the running of a sequence. It is useful if you have a variable time length process, function or procedure that you require the Agent to wait for it's completion. It basically sets a flag in the DLL, which halts the sequence execution until the flag is cleared again.

Parameters:

(Flag,app,proc,option)

Flag:	Determines whether to set or clear the DLL's global wait flag. Set halts the sequence and clear allows it to continue.
App:	Reserved for future use.
Proc:	Reserved for future use.
Option:	Reserved for future use.

Returns:

Nothing

ds_RecieveItemMap (string,<long>,<long>,<long>,<string>),long,proc

This is a procedure (which may be called as a function) which tells the DLL the "Map" of how to get to the desired item on the menu. The agent.dll will post an EVENT:UserItem to the exe and will then wait for the exe to issue a "Map" to get to the Item.

Parameters:

(MapK,D1,D2,Opt,Extra)

MapK:	A string containing the key strokes to press to get to the required menu item. The first letter is the hot key to press to drop the first menu down. The DLL will immediately press the ESCKey so that the first menu does not appear. If the first item/menu on the menubar is an item then when the item is required, no directs will follow (except the E). R = Right Key, D = Down Key, E = EnterKey.It must end in E and have only one E in the string.
D1:	A long indicating the delay between right and down keys (This defaults to 30 msec if omitted).
D2:	A long indicating delay between getting to item and pressing the enter key (This defaults to 70 msec if omitted).
Opt:	A long reserved for later use.
Extra:	A string reserved for later use.

Returns:

A long indicating the length of the map string (useful for error checking).

ds_MsAFileNames (<string>,<string>,<long>),long,proc

This is a function (which may be called as a procedure) which tells the agent.DLL the path (if required) and file name of the sequence file.

Parameters:

(FN,CFN,Options)

FN:	The file name (including the path if required to be fixed) of the file containing the sequences. If omitted, this defaults to 'Agent.csa'.
CFN:	The filename used for the characters and gestures tables.
Options:	A bit loaded long with the following parameters:

Bit0	Don't display error messages
Bit1	Use Agent.tps for Characters file.
Bit2	Don't display warnings when agents/OCX not loaded
Bit3	Clear FileNames, so Special Agent is Disabled
Bits4-8	Reserved for later use
Bytes1-4	Template Version indicator. Convert the top 4 bytes to hex, shift 3 bytes and divide by 100. So Version 1.35 would be passed as: 013500xH, where x are the options indicated above. For previous versions (before 1.35), the version was passed in decimal. Thus, the version was indicated by 132000 for version 1.32. This caused problems with the bit loaded options.

Returns:

A long. It returns a 0 if a suitable name was passed. Any other value indicates a failure.

ds_SendPosition(<string>,<long>)

This is a procedure that informs the agent.DLL of the position and dimensions of the window in question. The template calls this procedure everytime that a window is opened or sized/moved (if the IMM attribute is on). You will need to use this function if your window has no IMM attribute and you don't want the template to auto-apply the IMM attribute.

Parameters:

(ProcedureName,Options)

ProcedureName:	The name attribute of the procedure as used in the template (template variable %Procedure). This same name is used in the making of sequences and must correspond to those names.
Options:	A 1 for the frame procedure, else a 0.

Returns:

Nothing.

Functions not Available for General Use

ds_GetRunParam(),long
ds_GetRunString(string,long),string
ds_GetPosition(),string
ds_GetMenuItem(long,string,string,<long>),string
ds_GetMenuTip(long,<long>),String
ds_GetControlName(),string
ds_ThreadNotify(String,Long,String,<long>),long
ds_AgentControlQ(string,string,long,long,<string>)
ds_AddEvent(string,string,string,long,<long>)	[This function has now been replace with ds_AddEvent1, but is provided for backward compatability]
ds_AddEvent1(string,string,<string>,<long>,<long>)	[New function introduced in version 1.16]

[End of document]

meatloaf@capesoft.com