Galaxy Communicator Documentation:

The Builtin Server

License / Documentation home / Help and feedback

The builtin server is built into the Hub. It provides administrative support, as well as an additional body of functionality the MIT group has found useful.

Usage

Message Set

MIT functionality

• hub_turn_management
• dispatch_token
• dispatch_to_main
• increment_utterance
• abort_main
• reset_history

General functionality

• call_program
• new_session
• end_session
• destroy
• nop
• log_keys
• modify_properties
• get_properties
• set_session
• hub_print
• hub_break
• hub_exit
• hub_raise_error
• hub_available_servers
• hub_ping
  
• hub_token_owner
• hub_pause
• hub_sleep
  
• hub_set_verbosity
• hub_continue
• hub_gui_notify
• hub_token_timestamp
• hub_gc_version
  

The actions are:

• scratch_that: removes the last utterance from processing and the discourse history.

	parameter	type	optional	depends on	description/constraints
IN:	:session_id	string	yes		string which identifies the session; defaults to "Default"

 Returns one of the strings "scratched", "unscratched".
 
• clear_history: clears the discourse history.

	parameter	type	optional	depends on	description/constraints
IN:	:session_id	string	yes		string which identifies the session; defaults to "Default"

 Returns the string "history_cleared".
 
• close_off: interpretation of user's utterance "goodbye"

	parameter	type	optional	depends on	description/constraints
OUT:	:close_off	integer			value is 1

 Returns the string "goodbye".
 
• greetings: interpretation of user's utterance "hello"

	parameter	type	optional	depends on	description/constraints
OUT:	:greetings	integer			value is 1

 Returns the string "greetings".
 
• praise: interpretation of user's praise of the system

	parameter	type	optional	depends on	description/constraints
OUT:	:praise	integer			value is 1

 Returns the string "praise".
 
• vacuous: interpretation of vacuous user utterance

	parameter	type	optional	depends on	description/constraints
OUT:	:vacuous	integer			value is 1

 Returns the string "vacuous".
 
• domain_switch: switches the current domain for the session

	parameter	type	optional	depends on	description/constraints
IN:	:session_id	string	yes		string which identifies the session; defaults to "Default"
	:parse_frame	frame			the :parse_frame should have the form {...     :topic {...              :name "<name>"               ...           }    ... }
OUT:	:new_domain	string			Domain being switched to.
	:reply_frame	frame	yes		If the domain being switched to was previously encountered, this value is set (a continuation?).
	:welcome_frame	frame	yes		If the domain being switched to was not previously encountered, this value is set.

Returns NULL.
 
• unknown_word:

	parameter	type	optional	depends on	description/constraints
OUT:	:reply_frame	frame			copies the value of :parse_frame

 Returns NULL.
 
• no_parse

	parameter	type	optional	depends on	description/constraints
IN:	:session_id	string	yes		string which identifies the session; defaults to "Default"
OUT:	:reply_frame	frame			will be {c rejection_<num>    :no_parse 1    :domain <domain> } :domain will be set if the session has a domain specified; <num> is an internal index of failed parses.

 Returns NULL.
 
• call_me

	parameter	type	optional	depends on	description/constraints
IN:	:parse_frame	frame			the parse frame should have the form ...     :topic {...              :country_code "<country_code>"               :area_code "<area_code>"              :exchange "<exchange>"              :core "<core>"           }    :calling_domain <optional string: provides domain for session>    ... } where the phone number in the result will be <country_code>-<area_code>-<exchange>-<core>.
OUT:	:callback_channel	string			value is "telephone"
	:callback_address	string			value is "<country_code>-<area_code>-<exchange>-<core>"

 Returns the string "answer_phone".
• erase_all_history

Clears the Hub database history. Returns the string "history_cleared".

dispatch_token handles the details of invoking the program named in the :program key (default is "main") using the current message. It creates a new message by changing the name of the frame to the program name and removing the internal Hub state information from the frame. It updates session information from :out_lang, :para_lang, :kv_lang and :domain. The dispatch function dispatch_to_main simply deletes its incoming :program key and calls dispatch_token.

These messages are special because they will relay arbitrary keys to the new message, not just the keys which are listed here.
 

	parameter	type	optional	depends on	description/constraints
IN:	:session_id	string	yes		string which identifies the session
	:program	string	yes		program name to dispatch to; default is main
	:server_id	frame	yes	absence of :session_id	should be {... :server_name <string> :host <string> :port <int> :sock <int> ...}. All keys are optional. Used to compute value of :session_id, which ultimately defaults to "Default"
	:out_lang	string	yes		output language for the session
	:para_lang	string	yes		paraphrase language for the session
	:synth_lang	string	yes		synthesizer "language" for the session (that is, the name of the Genesis catalog for transduction from a string to a legal synthesizer input)
	:kv_lang	string	yes		key-value "language" for the session
	:domain	string	yes		name of the domain.
	:utterance_id	integer	yes		the utterance index
	:reply_clause_name	string	yes		for generating a :reply_frame for the "local" domain (that is, the builtin server)
	:no_abort	(not checked)	yes	value of :session_id and :utterance_id (after computation of output values)	blocks a previously-set abort for all utterances with this :utterance_id

This message returns NULL.

increment_utterance increments the various indices for recording how many utterances have been made.
 

	parameter	type	optional	depends on	description/constraints
IN:	:session_id	string	yes		string which identifies the session; defaults to "Default"
	:domain	string	yes		name of the domain.
OUT:	:utterance_id	integer			new utterance index

This message returns a frame.

abort_main sets an abort for a specified utterance. This function returns NULL.
 

	parameter	type	optional	depends on	description/constraints
IN:	:session_id	string	yes		string which identifies the session; defaults to "Default"
	:server_id	frame	yes	absence of :session_id	should be {... :server_name <string> :host <string> :port <int> :sock <int> ...}. All keys are optional. Used to compute value of :session_id, which ultimately defaults to "Default"
	:utterance_id	integer	yes		utterance index; defaults to the utterance index of the located session

This message does not return a frame.

reset_history saves away the existing history when a domain switch happens, and restores a previously stored history for the new domain (if it exists).
 

	parameter	type	optional	depends on	description/constraints
IN:	:session_id	string	yes		string which identifies the session; defaults to "Default". If there's no session, returns without switching
	:new_domain	string			name of the new domain

This message returns a frame.

call_program is a streamlined version of dispatch_token, which does not do any special processing on the current message beyond copying it, removing the Hub state information, and invoking the named program. It returns the final token state of the called program.

This message is special because it relays arbitrary keys to the called program, and in fact does not pass the :program key at all. It also returns arbitrary keys.
 

	parameter	type	optional	depends on	description/constraints
IN:	:session_id	string	yes		string which identifies the session
	:program	string			program name to dispatch to
	:inherit_timestamp	integer	yes		if present and non-zero, causes the new message to inherit the timestamp of the current token using GalSS_EnvInheritTokenTimestamp.

This message returns a frame.

new_session resets a session (opens a new logfile, resets utterance counter). If the session does not exist, it will be created. To make sure that logfiles are managed correctly when session IDs are reused, this function only opens a new logfile the second time it's called and each subsequent time. See the session management documentation for details.
 

	parameter	type	optional	depends on	description/constraints
IN:	:session_id	string	yes		string which identifies the session; defaults to "Default"

This message returns a frame.

end_session terminates the specified session. If a logfile is open, it will be closed.
 

	parameter	type	optional	depends on	description/constraints
IN:	:session_id	string	yes		string which identifies the session; defaults to "Default"

This message returns a frame.

destroy destroys the token.

This message returns a destroy token message reply. It does not return a normal reply.

nop is a no-op. It returns what is passed in.

log_keys invokes the logger. This message is special because it logs whatever keys are in the frame passed to it. The keys will be logged under a timestamped instance of the log_keys operation. This message returns the frame passed to it.

modify_properties updates properties in either the session or server Hub states. It deletes before it sets.
 

	parameter	type	optional	depends on	description/constraints
IN:	:namespace	string			identifies the Hub namespace to retrieve from (options are server or session)
	:properties_to_delete	list	yes		a list of keys to delete from the specified namespace
	:properties_to_set	frame	yes		a frame containing key-value pairs to add to the specified namespace (the name of the frame is ignored).

This message returns NULL. See the Hub properties documentation.

get_properties retrieves properties for either the session or server Hub states.
 

	parameter	type	optional	depends on	description/constraints
IN:	:namespace	string			identifies the Hub namespace to retrieve from (options are server or session)
	:properties	list			a list of keys to retrieve from the specified namespace

This message returns a frame containing the specified keys. See the Hub properties documentation.

set_session possibly creates a new session, and optionally assigns some session locks to it.
 

	parameter	type	optional	depends on	description/constraints
IN:	:session_id	string	yes		string which identifies the session; defaults to "Default".
	:lock_info	integer	yes		a logical OR of flags controlling how this session should be locked. See GalSS_EnvSetSession. If absent, the locks from the previous session will be used, if present.
	:previous_session_id	string	yes		a session to transfer locks from, if appropriate

This message returns NULL.

hub_print prints a message or the contents of a Hub namespace.
 

	parameter	type	optional	depends on	description/constraints
IN:	:namespace	string	yes		identifies the Hub namespace to display the contents of
	:message	string	yes		a string to display
	:verbosity	integer	yes		if present, restricts the printing to situations where GAL_VERBOSE exceeds the specified verbosity
	:session_locks	integer	yes		if nonzero, causes the Hub to print the status of all session locks
	:db	integer	yes		if nonzero, causes the Hub to print the contents of the current session utterance history DB

This message returns NULL.

hub_break enters a loop which allows the user to explore the current state of the Hub.
 

	parameter	type	optional	depends on	description/constraints
OUT:	:disable_break	integer			if 1, indicates that the user exited the loop requesting no further breaks

This message returns a frame

hub_exit causes the Hub to exit gracefully. This message returns NULL.

hub_raise_error raises an error using GalSS_EnvError. This function can be useful if you've caught an error using the ERROR: directive in a Hub program but you still want to raise an error for the caller.
 

	parameter	type	optional	depends on	description/constraints
IN:	:error_description	string			the description of the error to be passed to GalSS_EnvError.

This message returns NULL.

hub_available_servers returns the active service types in the Hub. This list may not match the list of defined service types due to the use of the SERVERS: directive in the program file.
 

	parameter	type	optional	depends on	description/constraints
OUT:	:servers	list of strings	no		a list of names of active service types

This message returns a frame.

hub_ping checks the status of a specified service provider or service type.  

This message returns a frame.

hub_token_owner returns the name of the service type of the provider originating the current token.
 

	parameter	type	optional	depends on	description/constraints
OUT:	:owner	string			The name of the service type for the provider originating the current token
	:owner_id	string			The provider ID of the provider originating the current token

This message returns a frame.

hub_pause sets a pause after each message dispatch. This can be useful for demoing and debugging.
 

	parameter	type	optional	depends on	description/constraints
IN:	:milliseconds	integer	yes		If present, the length of the pause in milliseconds

This message returns NULL.

hub_sleep sleeps for the specified number of milliseconds.
 

	parameter	type	optional	depends on	description/constraints
IN:	:milliseconds	integer	yes		If present, the length of the sleep in milliseconds

This message returns NULL.

hub_set_verbosity sets the verbosity level for the Hub, in addition to the command line argument to the Hub and the GAL_VERBOSE environment variable.
 

	parameter	type	optional	depends on	description/constraints
IN:	:verbosity	integer			Verbosity level (0 to  6)

This message returns NULL.

hub_continue listens for a new message of the specified form and treats it as a reply or error. See the section on Hub continuations for a discussion.
 

	parameter	type	optional	depends on	description/constraints
IN:	:reply_matches	list of frames	yes		If present, a sequence of frames one of which should match an incoming new message, which will then be treated as a normal reply. Matching is done using Gal_MatchFrame. One of this and :error_matches must be specified.
	:error_matches	list of frames	yes		If present, a sequence of frames one of which should match an incoming new message, which will then be treated as an error reply. Matching is done using Gal_MatchFrame. One of this and :reply_matches must be specified.
	:service_type	string	yes		If present, the name of a service type known to the Hub, which will serve as a filter on which providers will be monitored for new messages
	:service_provider	string	yes		If present, a provider name or service type which will server as a filter on which providers will be monitored for new messages. Overrides the value for :service_type if it conflicts.

This message returns the frame which matches one of the elements in :reply_matches or :error_matches.

hub_gui_notify relays messages to the Hub GUI, if there is one.

hub_token_timestamp retrieves the timestamp for the current token.

This message returns a frame.

hub_gc_version returns the current version of the Galaxy Communicator infrastructure. These values can be used to conditionalize behavior in Hub programs.

License / Documentation home / Help and feedback

Last updated August 13, 2002