The File adapter allows an agent to observe and manipulate files to which it has access. This can include files that reside on the same system as the agent, and also files on any file servers to which the agent has access. Normal file system security measures can be used to control an agent's access to files.
When coupled with an inference engine and a Time adapter, the File adapter lets you create rules to automatically:
Note to AIX users: In this version of Agent Building Environment Developer's Toolkit, the File adapter is not supported on AIX.
This event is generated by the File adapter when it detects that a file has been changed since the last time it was checked. Note that renaming a file will appear as a "FileDeleted" event, not as a "FileChanged" event.
This event is generated by the File adapter when it detects that a file has been created in a directory that was the target of an earlier "CheckDirectory" effector.
Same as "FileChanged" (above).
This event is generated by the File adapter when it detects one of two things:
This event is generated by the File adapter in response to a "CheckFile" effector when the designated file cannot be found. If the file exists, but some other problem occurs (for example, the file exists but the user or agent is not authorized to access it), a "FileError" event (see below) is generated instead.
This event can also be generated when the target of other file-oriented effectors (e.g., MoveFile, ExecuteFile, etc.) cannot be found.
Same as "FileDeleted" (above).
This event is generated by the File adapter when an error (other than not being able to find the file to be copied) occurs during the execution of the "CopyFile" effector.
Same as "FileDeleted" (above).
This event is generated by the File adapter when an error (other than not being able to find the file to be moved) is encountered during execution of the "MoveFile" effector. For example, if you try to move a file to a destination file name that already exists, a "MoveFailed" trigger event will be generated.
Same as "FileDeleted" (above).
This event is generated by the File adapter when an error (other than not being able to find the file to be deleted) is encountered during execution of the "DeleteFile" effector.
Same as "FileDeleted" (above).
This event is generated by the File adapter when an error (other than not being able to find the file to be executed) is encountered during execution of the "ExecuteFile" effector. For example, specifying a non-executable file as the target of an "ExecuteFile" effector will produce an "ExecuteFailed" event. An "ExecuteFailed" event means that the file adapter could not start the program in the specified file for some reason. Similarly, the absence of an "ExecuteFailed" event does not mean that the specified program completed successfully and achieved its objectives. Absence of an "ExecuteFailed" event only means the specified program was successfully started. The program might subsequently terminate abnormally -- this is not monitored, and no event is generated.
Same as "FileDeleted" (above).
This event is generated by the File adapter when an error (other than not being able to find the file) occurs during the execution of the "CheckFile" effector.
Same as "FileDeleted" (above).
This event is generated by the File adapter when an error occurs during the execution of the "AppendFile" effector.
Same as "FileDeleted" (above).
This event is generated by the File adapter when a directory that is the object of a "CheckDirectory" effector becomes empty. "DirectoryEmpty" can be generated at two particular times:
Note that subsequent "CheckDirectory" operations will NOT generate corresponding "DirectoryEmpty" events (UNLESS files that match the directory search pattern are added to, and then deleted from, the directory.
Also note that "DirectoryEmpty" signals that there are no more files that match the "DirectoryName" and "SearchPattern" predicates. It does NOT necessarily mean that there are no more files OF ANY SORT in "DirectoryName", only that there are no more that match "SearchPattern". For example, a "DirectoryEmpty" with predicates "c:\fred\barney\" and "*.bar" does NOT preclude the existence of a file "c:\fred\barney\read.me". It only precludes the existence of any file "c:\fred\barney\(somename).bar", where (somename) can be any file name.
This event is generated by the File adapter whenever an error is encountered during the execution of "CheckDirectory" sensor.
Same as "DirectoryEmpty" (above).
Given a full filename (drive:\path\name.ext), this (boolean) sensor returns TRUE if the file exists, and FALSE if it does not.
FileName, bound, string - The full name of the file whose existence is being tested.
This effector checks the status of a file. The first time "CheckFile" is invoked on a file, that status of the file (size, date and time last written) is captured. Subsequent invocations of "CheckFile" on that file will query the current status of the file. If the current status is different from the prior (captured) status, a "FileChanged" trigger event is generated.
DirectoryName, bound, string - The directory (drive and path information) of the file to be checked. It should terminate with a path delimiter, since it will be concatenated with the "ShortFileName" term to create the complete name of the file to be checked. Failure to terminate the "DirectoryName" term with a path delimiter will almost certainly result in a "FileNotFound" event being generated in response to the "CheckFile" sensor.
ShortFileName, bound, string - The name of the file to be checked.
For example, to check the file "c:\fred\barney\foo.bar", you would write the following antecedent in a rule:
(CheckFile "c:\fred\barney\" "foo.bar")
This effector specifies a directory to be checked. The first time "CheckDirectory" is invoked on a directory, the information about the files in the directory (that match the search pattern, see "Terms" below) is captured. If there are no files in the directory that match the search pattern, a "DirectoryEmpty" event is generated. Subsequent invocations of "CheckDirectory" on the directory will compare the current status of files in the directory with the previously-captured status.
If "ALL" is specified as a term, then "CheckDirectory" will:
If all the files in the directory matching the search pattern have been deleted, then, in addition to the "FileDeleted" events for each of those files, a "DirectoryEmpty" event is generated. Note that a "DirectoryEmpty" event does NOT mean that the directory specified by "DirectoryName" is completely empty, it only means there are no more files that match "SearchPattern". Only if the search pattern is "*.*" will the "DirectoryEmpty" event indicate that a directory is completely empty. See the section on the "DirectoryEmpty" trigger event for more information.
DirectoryName, bound, string - The directory name (drive and path information) of the directory to be checked. As in the case of "CheckFile", this term should end with a path delimiter, since it will be concatenated with the next term to provide a complete search argument.
SearchPattern, bound, string - The search pattern to specify what files within the directory should be checked. The search pattern "*.*" specifies all files in the directory should be checked.
Selector, bound, string - The only valid values for this term are "ALL" and "ONE", and one of these two choices must be specified. If "ONE" is specified, then regardless of how many files have been modified, deleted, or created since the last "CheckDirectory", only one trigger event will be generated (if no files have been modified, deleted, or created, then no trigger events will be generated). The type of trigger event ("FileChanged", "FileDeleted", or "FileCreated") and the name of the file that is reported on is unpredictable. If "ALL" is specified, then an event is generated for each file in the directory and satisfying the search pattern that has been deleted, created, or changed.
This effector copies the designated file to the target file. If the designated file cannot be found, a "FileNotFound" trigger event is generated. If any other error occurs in the course of copying the file, a "FileError" trigger event is generated.
SourceDirectoryName, bound, string - The directory name (drive and path specification) of the file to be copied. It should end in a path delimiter, since it will be concatenated with the "SourceShortFileName" to give the complete name of the file to be copied.
SourceShortFileName, bound, string - The file name of the file to be copied.
DestDirectoryName, bound, string - The directory name (drive and path specification) of the destination file. It should end in a path delimiter, since it will be concatenated with the "DestShortFileName" to give the complete name of the target file.
DestShortFileName, bound, string - The file name of the destination file.
For example, to copy the file "c:\fred\barney\foo.bar" to the file "d:\wilma\betty\poo.bah", you would write the following antecedent in a rule:
(CopyFile "c:\fred\barney\" "foo.bar" "d:\wilma\betty\" "poo.bah")
This effector moves the designated file to the target file. If the designated file cannot be found, a "FileNotFound" trigger event is generated. If any other error occurs in the course of moving the file, a "MoveFailed" trigger event is generated. For example, attempting to move a file to a destination file that already exists will cause a "MoveFailed" trigger event to be generated.
Note that any subsequent "CheckFile" operations on the source file will result in "FileNotFound" events being generated.
A simple effector to delete the specified file. If the file cannot be found, a "FileNotFound" event is generated. Otherwise, no event is generated.
DirectoryName, bound, string - The directory name (drive and path specification) of the file to be deleted. It should end in a path delimiter, since it will be concatenated with the "ShortFileName" to give the complete name of the file to be deleted.
ShortFileName, bound, string - The file name of the file to be deleted.
This effector causes the specified file to be executed. If the file is not executable, a "FileError" event will be generated. If the file cannot be found, a "FileNotFound" event will be generated.
DirectoryName, bound, string - The directory name (drive and path specification) of the file to be executed. It should end in a path delimiter, since it will be concatenated with the "SourceShortFileName" to give the complete name of the file to be executed.
ShortFileName, bound, string - The file name of the file to be executed.
Arguments, bound, string - A string comprising a list of arguments to be passed to the executable when it is invoked.
For example, the antecedent
(ExecuteFile "F:\IBMCPP\BIN\" "NMAKE.EXE" "/F FILEADAP.MAK")in a rule would trigger the VisualAge C++ "make" utility, passing it the parameters "/F FILEADAP.MAK".
This effector causes the specified string to be appended to the specified file. A newline character and a carriage return character ('\n' and '\r') are automatically added at the end of the text being appended to the file.
DirectoryName, bound, string - The directory name (drive and path specification) of the file to be appended to. It should end in a path delimiter, since it will be concatenated with the "ShortFileName" to give the complete name of the file to be appended to.
ShortFileName, bound, string - The file name of the file to be appended to.
Text1, bound, string - A string to be appended to the file.
Text2, bound, string - Another string to be appended to the file.
Note that either "Text1" or "Text2" can be variables. This is illustrated in the first example in the "Sample Rules" section below.
Here are a few sample rules, indicating possible ways the trigger events, sensors, and effectors of the file adapter could be used to backup files. Note that a rule like "if A and B then C" is written as
(=> (and A B) C)
(=> <antecedent> <consequent>)
To improve readability, some rules have been split across multiple lines. In the run-time environment, each rule is contained entirely on one line.
Consider the following set of rules, whose effect is to automatically create an "incremental backup" of Lotus Wordpro documents once a day -- files that have been changed or created since the last backup are copied, files that have not been changed are not copied:
(=> (and (and (EventName "File:FileChanged") (ShortFileName ?x) ) (DirectoryName "d:\lotsuite\wordpro\docs\") ) (and (CopyFile "d:\lotsuite\wordpro\docs\" ?x "g:\wordpro\backup\" ?x) (AppendFile "g:\wordpro\backup\" "backup.log" "Backing up file " ?x) ) )
(=> (and (and (EventName "File:CopyFailed")(FileName ?y)) (DirectoryName "d:\lotsuite\wordpro\docs\") ) (AppendFile "g:\wordpro\backup\" "backup.log" "ERROR backing up file" ?y) )
The HTTP adapter can be used to retrieve pages from the world wide web and allow inferencing to occur based on the HTTP header tags from the page. The HTTP stream and/or the content from the page can be retrieved from the adapter to allow other engines or adapters to perform additional processing.
This adapter is selector-enabled. All trigger events contain the selector that caused the event to occur. Proxy and Socks servers are associated with a particular selector, so different selectors can use different servers. And each selector has it's own monitor list,
This adapter maintains selector-specific data across a conduct set reload. Any servers that have been set up and any URL's that are being monitored are preserved across the reload. If you wish to reset these values, you must explicitly invoke the appropriate effectors during the AGENT:CSCHANGE event.
Note: Due to limitations in the engine which disallow transfer of binary data on sensors, this adapter presently retrieves only text.
This event is triggered when the adapter has successfully retrieved the page from the world wide web. This event must occur before any inferencing can be done on the page.
Term: string - URL of the page that was retrieved
Term: string - Title:
Term: string - value from the Title: header tag, if it exists
Term: string - Content-Type:
Term: string - value from the Content-Type: header tag, if it exists
Term: string - Content-Length:
Term: string - value from the Content-Length: header tag, if it exists
Term: string - Last-Modified:
Term string - value from the Last-Modified: header tag, if it exists
This event is triggered when the adapter has detected that a given web page has changed since the last time we retrieved it. The new version of the page is available for inferencing.
Term: string - URL of the page that has changed
Term: string - Title:
Term: string - value from the Title: header tag, if it exists
Term: string - Content-Type:
Term: string - value from the Content-Type: header tag, if it exists
Term: string - Content-Length:
Term: string - value from the Content-Length: header tag, if it exists
Term: string - Last-Modified:
Term: string - value from the Last-Modified: header tag, if it exists
This event is triggered when the AddURLtoMonitorList effector is unable to retrieve the page from the world wide web (usually due to server errors). This event indicates that the URL was NOT added to the monitor list. You can force the URL to be added anyway by invoking the AddURLtoMonitorList2 effector with the ForceAdd parameter.
Term: string - URL of the page that was not added to the monitor list
Term: string - Brief message containing the reason the add failed.
All HTTP adapter sensors ignore the event header selector.
Returns all of the data that was returned from the HTTP Get request. This includes the HTTP header and the content.
Buffer, free, string - a variable into which the stream data will be 'placed'
Returns just the content from the HTTP stream. For an HTTP stream with content-type of text/html, this will return the text/html (without the HTTP header).
Buffer, free, string - a variable into which the data will be 'placed'
Retrieves or verifies the value of a given HTTP header tag.
Note: The HTTP version and response code can be sensed by this function using "HTTP-Version:" and "Response-Code:" as tag names, respectively.
Tag name, bound , string - The name of the HTTP header tag that is being sensed.
The tag name should include the ending colon. For example, "Content-Type:" or "Server:".
Tag value, free or bound, string - string containing value of header tag.
For example, "text/html" would be a tag value for tag header "Content-Type:".
When free, the sensor retrieves the tag value from the web page and returns it.
When bound, the sensor treats this as a request to confirm whether the specified tag value is the tag value that is contained in the web page for the given header tag.
All HTTP adapter effectors ignore the event header selector.
This effector establishes the proxy server that should be used by the adapter for web communications.
Proxy URL, bound , string - The URL of the proxy.
Note that the URL should be of the form "http://a.b.c/" or "http://a.b.c:port/".
At least one server (proxy or socks) must be set before the adapter is started. Recommendation is to invoke the effector when the AGENT:STARTING trigger event occurs.
OS/2
None
Windows 95/NT
If the adapter issues messages indicating that it cannot resolve one or more host names, then update the Windows TCPIP properties so that the name server IP address for the proxy is the first address in the list.
See note under SetHTTPSocks for additional information.
AIX
None
This effector establishes the socks server that should be used by the adapter for web communications.
Socks URL, bound , string - The URL of the socks server.
Note that the URL should be of the form "a.b.c" or "a.b.c:port".
At least one server (proxy or socks) must be set before the adapter is started. Recommendation is to invoke the effector when the AGENT:STARTING trigger event occurs.
OS/2
None
Windows 95/NT
The name server IP address of the socks server must be configured as the first domain name server in the TCPIP configuration. If not, the adapter will be unable to resolve host names using the socks server.
To update the TCPIP configuration, choose START, Settings, Control Panel. Double click the Network Icon, and click on the Configuration tab. Hilight TCPIP in the 'installed components' list, and then click the PROPERTIES button. Click the DNS Configuration tab, click the 'enable DNS' box, and then add the IP address to the DNS server search list.
AIX
None
This effector will retrieve a page from the web. When the page arrives, it will generate a webPageArrived trigger event.
URL, bound , string - The URL of the page that is to be retrieved.
Note that the URL should be of the form "http://a.b.c/" or "http://a.b.c/whatever..." (the ending slash is required after the domain name - i.e. "http://a.b.c" is invalid).
This effector will add a URL to the monitored-pages list, so that subsequent invocations of CheckMonitoredPagesForChanges will check this URL for changes. If the URL cannot be retrieved from the web, an addFailed event is generated and the URL is not added to the monitor list.
URL, bound , string - The URL of the page that is to be added to the list.
Note that the URL should be of the form "http://a.b.c/" or "http://a.b.c/whatever..." (the ending slash is required after the domain name - i.e. "http://a.b.c" is invalid).
This effector is the same as AddURLtoMonitorList, except that it takes an additional parameter which allows you to specify what action to take if a server error prevents the page from being retrieved from the web.
URL, bound , string - The URL of the page that is to be added to the list.
Note that the URL should be of the form "http://a.b.c/" or "http://a.b.c/whatever..." (the ending slash is required after the domain name - i.e. "http://a.b.c" is invalid).
symbol - Indicates what action to take when an error occurs retrieving the page from the web.
Note that this will cause a webPageChanged event the first time the page is successfully retrieved from the web on a CheckMonitoredPagesForChanges effector.
This effector will delete a URL (or all the URL's) from the monitored-pages list, so that subsequent invocations of CheckMonitoredPagesForChanges will NOT monitor this URL for changes.
URL, bound , string - The URL of the page that is to be removed from the list, or the string keyword "ALL".
Note that the URL, if specified, should be of the form "http://a.b.c/" or "http://a.b.c/whatever..." (the ending slash is required after the domain name - i.e. "http://a.b.c" is invalid).
The keyword ALL will reset the monitor list to contain no url's.
This effector will check all the web pages on the monitored-pages list for changes in the page.
Each page on the list is retrieved from the web and compared against the previously-retrieved version of the page. If the new version is different than the old version, the effector will trigger a webPageChanged event.
Note: This function uses a checksum method against the content of the HTTP request to 'compare' the page content. Any difference in the checksums, or any change in the Last-Modified date in the HTTP header (if it exists), will cause a 'change' to be detected.
None, bound or free, string - No terms are required by the adapter for this effector.
However current engine implementation requires at least one term, so the adapter defines the term as a string. A null string ( "" ) is acceptable.
Here are a few sample rules, indicating possible ways the trigger events, sensors, and effectors of the HTTP adapter could be used to access web pages. Note that a rule like "if A and B then C" is written as
(=> (and A B) C)
(=> <antecedent> <consequent>)
To improve readability, some rules have been split across multiple lines. In the run-time environment, each rule is contained entirely on one line.
The NNTP (Network News Transfer Protocol) adapter allows a user to retrieve news articles from the Internet's USENET newsgroups, and to screen them using personalized criteria.
When coupled with an inference engine, the NNTP adapter lets you create rules which will select or reject articles based on the content of the article or article header, the author of the article, the size of the article, and other criteria. If used in conjunction with a Time adapter to determine times or intervals at which to forage for news articles and with an EMail adapter (for example) to forward selected articles, the NNTP adapter can form the basis of a USENET news filtering application.
Note: When the NNTP adapter is part of an agent configuration, then the NNTP adapter conduct set must be loaded before the agent is started. Otherwise the NNTP adapter will fail to start.
This event is generated by the NNTP adapter when it has successfully retrieved an article from a USENET newsgroup.
Given a word or phrase to search for, checks if that string occurs as whitespace- or punctuation-delimited text within the article body, where the article body is all of the article text after the header fields (the header and the body are separated by double newlines). Whitespace within the search string matches any whitespace in the article body (which allows you to find phrases that cross line boundaries, for example).
Given a word or phrase to search for and a USENET header field name (e.g. "subject", "organization", etc.), checks if that phrase occurs as a whitespace-delimited string within the specified header field (absence of the requested header field altogether is equivalent to not finding the phrase). For the header field "subject" only, the phrase will be found if it is punctuation-delimited as well (for example, KeyInHeader("subject" "Java" 1) would match the subject "what about Java!?!?!?"). Whitespace within the search string matches any whitespace in the header field.
Given a person's name, determines if the article was sent by that person, according to the article's "From:" field. This sensor ignores the part of the "From:" field specifying the author's electronic address, looking only for the optional human name. IsFrom will sense a partial name match. So if, for example, only "Bob" or "Smith" is given, IsFrom will successfully match articles from "Bob Jones" or "Jane Smith", respectively.
Given a person's email address (e.g. "beth@company.com"), determines if the article was sent by that person, according to the article's "From:" field. This sensor ignores the optional part of the "From:" field specifying the author's name, looking only for the electronic address.
Given a newsgroup name, determines if the article is posted to that newsgroup. A trailing asterisk may be used in the newsgroup name (for example, using "alt.*" would sense if the article is posted to any group in the "alt." hierarchy of USENET).
Determines if the article contains uuencoded data.
Determines if the article claims to be MIME-encoded. If the term passed is "any", IsMIME merely checks that the article contains a "MIME-Version" header field. If the term is any string containing a slash ("/"), IsMIME checks whether this is the value of the entire "Content-Type" header field (e.g. "image/gif"). If the term is any other string, IsMIME checks whether this is the "type" part of the "Content-Type" header field, ignoring any subtype or parameter (for example "text" would match "text/plain; charset=US-ASCII").
Determines if the number of lines in the article body is within the given range (inclusive). This relies on the optional header field "Lines:", if it is present. Otherwise an actual line count is done.
Used to sense the entire contents of the article (header and body).
This effector selects the name to give the history file (which keeps track of which articles have already been retrieved), the news server from which to forage articles, and the port to connect to the server on (typically 119, which is the well-known port for NNTP). The user should code a rule to drive this effector on an AGENT:STARTING event, so that when the NNTP adapter is started it will have this needed initialization information.
This effector selects a newsgroup from which articles are retrieved. You may specify a trailing asterisk to forage all articles in a certain hierarchy. For example, you could specify "alt.movies.*" to forage in all newsgroups whose names begin with "alt.movies.". (Be aware, however, that this use of trailing asterisks may cause significant degradation in startup performance.) The user should code a rule or rules to drive this effector on an AGENT:STARTING event, so that when the NNTP adapter is started it will have this needed initialization information.
This effector tells the adapter to retrieve articles. It retrieves articles from all the groups specified on previous AddNewsgroup effector calls, fetching them from the server specified by a previous SelectHistoryFile effector call. For each article successfully retrieved, GetNews will generate a NNTP:NEW_NEWS event. GetNews keeps track of all articles it has fetched in a history file, so that subsequent invocations will not re-fetch the same articles. Typically, the user would write a rule or rules to drive this effector based on some time-based event (for example, GetNews every n hours).
A simple effector to display an article to standard output. This effector is useful for testing rules.
Here are a few sample rules, indicating possible ways the trigger events, sensors, and effectors of the NNTP adapter could be used to filter news. Note that a rule like "if A and B then C" is written as
(=> (EventName "AGENT:STARTING") (setIntervalAlarm 240 "minutes"))
(=> (and (EventName "Time:IntervalAlarm")(Interval 240 "minutes")) (GetNews "token"))
(=> (and (EventName "NNTP:NEW_NEWS") (InGroup "comp.lang.*")) (About "programming"))
(=> (and (EventName "NNTP:NEW_NEWS") (KeyInHeader "subject" "garbage collection" 0)) (About "gc"))
(=> (and (About "programming") (About "gc")) (About "gc in programming"))
(=> (and (About "gc in programming") (TextIs ?x)) (Email "me@myplace" ?x))
The time adapter deals with the domain of time. It provides information about time and performs operations with time such as ordering and arithmetic operations. It provides the capability of setting timers or alarms which will subsequently generate Trigger Events. In all sensors, effectors and facts that contain dates, the date is formatted as "YYYY-MM-DD". In the sensors, effectors, and facts, the time is formatted as "HH:MM:SS". Weekdays are represented by a number 0-6. Sunday is 0 ... and Saturday is 6.
This adapter is a core adapter and is used to get (query through sensors) time information and set alarms to trigger events for actions by other adapters.
The time adapter supports persistent alarms. If persistence is enabled, and the agent is terminated, those alarms categorized as persistent will be set when the agent starts again if persistence is enabled with the same filename. All alarm transactions are saved as they are processed. If alarms set by rules duplicate those that are persistent, the persistent alarms will have priority. The effector, "setDuplicateHandling" describes this in more detail. The effector, "setPersistentCategories" describes how to categorize alarms as persistent.
There are three categories of time adapter effectors. The first set of effectors provides configuration information. These effectors must be triggered by rules based on the AGENT:CONFIG event because they are needed before any alarms are set. These effectors are ignored if they are presented on any other event.
The second set of effectors sets or turns off alarms. Each alarm has both an identifier and category associated with it. If the identifier is empty, "" , a default identifier is used.
Alarms with default identifiers are handled differently than ones with identifiers specified to provide compatibility with un-identified alarms in previous releases. These are the differences in how alarms with default identifiers are handled.
Each alarm also has a category associated with it. This is specified in the effector to set the alarm. If the category is empty, "", a default category is assigned. If the alarm is set on the AGENT:STARTING event, the default category is "init", otherwise the default category for the alarm is "other". This category is used to define whether the alarm is persistent if persistence is enabled (see the effector, setPersistentCategories) or whether it is affected by a particular reset effector ( see the description of this effector). Alarm categories *MUST* be strings with no white space.
Alarms should not be set on the AGENT:CONFIG event. Any effectors which set alarms are ignored by the Time Adapter on the AGENT:CONFIG event.
There are two other special effectors
There are several ways to query time/date through sensors:
All Trigger Events result from an alarm. Each alarm is associated with a selector that was contained on the eventHeader when the alarm was set. The eventHeader with each TriggerEvent presented by the time adapter will contain the selector associated with that alarm.
The Time Adapter presents only one type of event. This event is a timer event that results from setting an alarm.
This fact gives the date and time for which the alarm was set.
The first term is a string in date format.
The second term is a string in time format.
This fact provides one term - an integer representing the day of the week.
This has one term, a string, which is the identifier of the alarm.
This has one term, a string, which is the category of the alarm.
This fact provides one term - an integer representing the number of intervals missed before this alarm was triggered. If this was not a recurring alarm, this value would always be 0.
This fact gives the interval for which the alarm was set. This fact only applies to interval alarms.
The first term is an integer representing the interval amount.
The second term is the integer units, a string - the valid values are "seconds", "minutes", "hours", "days", "months", or "years".
This fact provides one term - an integer representing the number of intervals remaining. This fact only applies to Alarm events that are associated with interval alarms that have an ending time.
None of the information in the eventHeader is pertinent to any sensor in the time adapter and therefore is ignored. That is, the query answered by each sensor is independent of the event to which this sensor is related.
Given two date and times, answers true if the first is after the second.
First date - string (date format) is the date of the first time
First time - string (time format) is the 24 hour time of the first time
Second date - string (date format) is the date of the second time
Second time - string (time format) is the 24 hour time of the second time
Given two date and times, answers true if the first is before the second.
First date - string (date format) is the date of the first time
First time - string (time format) is the 24 hour time of the first time
Second date - string (date format) is the date of the second time
Second time - string (time format) is the 24 hour time of the second time
Given a date and time, answers true if the current time is after the given one.
date - string (date format) is the date
time - string (time format) is the 24 hour time
Given a date and time, answers true if the current time is before the given one.
date - string (date format) is the date
time - string (time format) is the 24 hour time
Given three date and times, answers true if the second is between the first and the third.
First date - string (date format) is the date of the first time
First time - string (time format) is the 24 hour time of the first time
Second date - string (date format) is the date of the second time
Second time - string (time format) is the 24 hour time of the second time
Third date - string (date format) is the date of the third time
Third time - string (time format) is the 24 hour time of the third time
Given two date and times, answers true if the current time is between the first and the second.
First date - string (date format) is the date of the first time
First time - string (time format) is the 24 hour time of the first time
Second date - string (date format) is the date of the second time
Second time - string (time format) is the 24 hour time of the second time
Given two date and times, answers true if they are equal.
First date - string (date format) is the date of the first time
First time - string (time format) is the 24 hour time of the first time
Second date - string (date format) is the date of the second time
Second time - string (time format) is the 24 hour time of the second time
Given two date and times, answers true if they are not equal.
First date - string (date format) is the date of the first time
First time - string (time format) is the 24 hour time of the first time
Second date - string (date format) is the date of the second time
Second time - string (time format) is the 24 hour time of the second time
Given a date and time, answers true if they are equal to the current time.
date - string (date format) is the date
time - string (time format) is the 24 hour time
Given a date and time, answers true if they are not equal to the current time.
date - string (date format) is the date
time - string (time format) is the 24 hour time
Given a digit representing a day of the week, answers true if it matches the current day of the week.
weekday - String
Given a digit representing a day of the week, answers true if it is day 0 or 6.
weekday - String
Answers true if the current day of the week is 1-5.
a symbol=True
Answers true if the current day of the week is 0 or 6.
a symbol=True
Returns the current date and time
date - string (date format) is the date
time - string (time format) is the 24 hour time
Returns the current date
date - string (date format) is the date
Returns the current time
time - string (time format) is the 24 hour time
Returns the current day of the Week
day of Week - String (0, 1, 2, 3, 4, 5, or 6)
adds a given interval to a date and time and returns a date and time
First date - string (date format) is the date of the first time
First time - string (time format) is the 24 hour time of the first time
interval - integer representing amount to be added to first date and time
interval units - string ("seconds", "minutes", "hours", "days", "months", or "years") representing the units of the interval to be added to the first date and time
Second date - string (date format) is the date of the second time resulting from adding the interval to the first date and time
Second time - string (time format) is the 24 hour time of the second time resulting from adding the interval to the first date and time
Takes two date and times and determines the interval between the two
First date - string (date format) is the date of the first time
First time - string (time format) is the 24 hour time of the first time
Second date - string (date format) is the date of the second time
Second time - string (time format) is the 24 hour time of the second time
interval - integer representing the seconds between the two date and times
The selector contained in the eventHeader for each effector is associated with an alarm if it is being set, or used in finding the specific alarm associated with that selector if it is being turned off. When a selector is associated with an alarm, it will be presented in the eventHeader with each subsequent TriggerEvent for that alarm.
This turns off an alarm. It is matched only by the alarm identifier.
AlarmId - string identifying the alarm to turn off
This sets an alarm for the given time. The alarm has an identifier and category associated with it. The description of the use of the identifier and category is in the time adapter overview. A default value is assigned for the identifier or category if a "" is specified. If the alarm is set on the AGENT:STARTING event, the default category is "init", otherwise the default category for the alarm is "other". Alarm categories must be strings with no white space. The default identifier is the date string of the alarm followed by a blank and the time string of the alarm, eg. "1996-06-23 18:15:00".
Date - string (date format) is the date to be set for the alarm
Time - string (time format) is the 24 hour time of the time to be
AlarmId - string identifying the alarm
Category - string identifying the alarm category
This sets a recurring alarm for a given interval. The alarm has an identifier and category associated with it. The description of the use of the identifier and category is in the time adapter overview. A default value is assigned for the identifier or category if a "" is specified. If the alarm is set on the AGENT:STARTING event, the default category is "init", otherwise the default category for the alarm is "other". Alarm categories must be strings with no white space. The default identifier is the interval of the alarm followed by a blank and the interval units followed by " 0 0", eg. "1 hours 0 0".
interval - integer representing the quantity of the interval
interval units - string ("seconds", "minutes", "hours", "days", "months", or "years") representing the units of the interval.
AlarmId - string identifying the alarm
Category - string identifying the alarm category
This sets a recurring alarm for a given interval to start at a specific time (or, in the case of alarm with a default identifier, at the next alarm boundary after the given start time). The alarm has an identifier and category associated with it. The description of the use of the identifier and category is in the time adapter overview. A default value is assigned for the identifier or category if a "" is specified. If the alarm is set on the AGENT:STARTING event, the default category is "init", otherwise the default category for the alarm is "other". Alarm categories must be strings with no white space. The default identifier is the blank delimited sequence of the interval, interval units, start date string, and start time string, eg. "1 hours 1997-06-23 20:38:00".
interval - integer representing the quantity of the interval
interval units - string ("seconds", "minutes", "hours", "days", "months", or "years") representing the units of the interval.
start date - string (date format) is the date to be the basis for the first alarm
start time - string (time format) is the 24 hour time of the time to be basis for the first alarm.
AlarmId - string identifying the alarm
Category - string identifying the alarm category
This sets a recurring alarm for a given interval. The ending date and time tell when to cancel the alarm. The alarm has an identifier and category associated with it. The description of the use of the identifier and category is in the time adapter overview. A default value is assigned for the identifier or category if a "" is specified. If the alarm is set on the AGENT:STARTING event, the default category is "init", otherwise the default category for the alarm is "other". Alarm categories must be strings with no white space. The default identifier is the blank delimited sequence of the interval, interval units, a "0 0", end date string, and end time string, eg. "1 hours 0 0 1998-06-23 20:38:00".
interval - integer representing the quantity of the interval
interval units - string ("seconds", "minutes", "hours", "days", "months", or "years") representing the units of the interval.
end date - string (date format) is the date to be the ending date of the recurring alarm.
end time - string (time format) is the 24 hour time to be the ending time of the recurring alarm.
AlarmId - string identifying the alarm
Category - string identifying the alarm category
This sets a recurring alarm for a given interval to start at a specific time (or, in the case of alarm with a default identifier, at the next alarm boundary after the given start time). The ending date and time tell when the alarm should be cancelled. The alarm has an identifier and category associated with it. The description of the use of the identifier and category is in the time adapter overview. A default value is assigned for the identifier or category if a "" is specified. If the alarm is set on the AGENT:STARTING event, the default category is "init", otherwise the default category for the alarm is "other". Alarm categories must be strings with no white space. The default identifier is the blank delimited sequence of the interval, interval units, start date string, start time string, end date string, and end time string, eg. "1 hours 1997-06-23 20:38:00 1998-06-23 20:38:00".
interval - integer representing the quantity of the interval
interval units - string ("seconds", "minutes", "hours", "days", "months", or "years") representing the units of the interval.
start date - string (date format) is the date to be the basis for the first alarm
start time - string (time format) is the 24 hour time of the time to be basis for the first alarm.
end date - string (date format) is the date to be the end date of the alarm.
end time - string (time format) is the ending time of the alarm.
AlarmId - string identifying the alarm
Category - string identifying the alarm category
This sets an Interval Alarm. A random start time is picked over the given randomization interval. The randomization interval is in number of seconds. If the value for the randomization interval is 0, the interval and interval units given for the alarm will be used. For example, if the number for the randomization interval is 60, a random start time within the next minute will be used for this alarm. If the randomization interval is 0, and the alarm is for an interval of 2 hours, a random start time within the next 2 hours will be used for this alarm.
The alarm has an identifier and category associated with it. The description of the use of the identifier and category is in the time adapter overview. A default value is assigned for the identifier or category if a "" is specified. If the alarm is set on the AGENT:STARTING event, the default category is "init", otherwise the default category for the alarm is "other". Alarm categories must be strings with no white space. The default identifier cannot be predicted since the alarm has a random start time. A non-default identifier should be specified on the alarm if it is needed in other rules, such as in an effector to turn off the alarm.
interval - integer representing the quantity of the interval
interval units - string ("seconds", "minutes", "hours", "days", "months", or "years") representing the units of the interval.
randomization interval - integer representing the seconds over which to randomize the start time
AlarmId - string identifying the alarm
Category - string identifying the alarm category
This sets a recurring alarm for a given interval. It generates an Alarm event. The start date sets the date for the first occurrence of the alarm. A random start time is picked based on the specified start time and randomization interval. The randomization interval is in seconds. For example, if the start time is 08:00:00 and the number for the randomization interval is 60 (seconds), a random start time between 08:00:00 and 08:00:60 is used for the alarm. If the value for the randomization interval is 0, the interval and interval units given for the alarm will be used.
The alarm has an identifier and category associated with it. The description of the use of the identifier and category is in the time adapter overview. A default value is assigned for the identifier or category if a "" is specified. If the alarm is set on the AGENT:STARTING event, the default category is "init", otherwise the default category for the alarm is "other". Alarm categories must be strings with no white space. The default identifier cannot be predicted since the alarm has a random start time. A non-default identifier should be specified on the alarm if it is needed in other rules, such as in an effector to turn off the alarm.
interval - integer representing the quantity of the interval
interval units - string ("seconds", "minutes", "hours", "days", "months", or "years") representing the units of the interval.
start date - string (date format) is the starting date of the alarm.
start time - string (time format) is the starting time of the alarm.
randomization interval - integer representing the seconds over which to randomize the start time
AlarmId - string identifying the alarm
Category - string identifying the alarm category
This sets a recurring alarm for a given interval. The alarm is not set on any particular boundary. It generates an Alarm event. The start date sets the date for the first occurrence of the alarm. A random start time is picked based on the specified start time and randomization interval. The randomization interval is in seconds. For example, if the start time is 08:00:00 and the number for the randomization interval is 60 (seconds), a random start time between 08:00:00 and 08:00:60 is used for the alarm. If the value for the randomization interval is 0, the interval and interval units given for the alarm is used. The ending date and time are specified. That is, the alarm is also end-bounded.
The alarm has an identifier and category associated with it. The description of the use of the identifier and category is in the time adapter overview. A default value is assigned for the identifier or category if a "" is specified. If the alarm is set on the AGENT:STARTING event, the default category is "init", otherwise the default category for the alarm is "other". Alarm categories must be strings with no white space. The default identifier cannot be predicted since the alarm has a random start time. A non-default identifier should be specified on the alarm if it is needed in other rules, such as in an effector to turn off the alarm.
interval - integer representing the quantity of the interval
interval units - string ("seconds", "minutes", "hours", "days", "months", or "years") representing the units of the interval.
start date - string (date format) is the starting date of the alarm.
start time - string (time format) is the starting time of the alarm.
end date - string (date format) is the ending date of the alarm.
end time - string (time format) is the ending time of the alarm.
randomization interval - integer representing the seconds over which to randomize the start time
AlarmId - string identifying the alarm
Category - string identifying the alarm category
This sets an alarm for the given time to reoccur every day at that time. The alarm has an identifier and category associated with it. The description of the use of the identifier and category is in the time adapter overview. A default value is assigned for the identifier or category if a "" is specified. If the alarm is set on the AGENT:STARTING event, the default category is "init", otherwise the default category for the alarm is "other". Alarm categories must be strings with no white space. The default identifier is the time string followed by a blank and the string "0123456", eg. "20:38:00 0123456".
time - string (time format) is the 24 hour time of the time to be set for the alarm.
AlarmId - string identifying the alarm
Category - string identifying the alarm category
This sets an alarm for the given time to reoccur on the days of the week specified. The alarm has an identifier and category associated with it. The description of the use of the identifier and category is in the time adapter overview. A default value is assigned for the identifier or category if a "" is specified. If the alarm is set on the AGENT:STARTING event, the default category is "init", otherwise the default category for the alarm is "other". Alarm categories must be strings with no white space. The default identifier is the time string followed by a blank and the string of the days of the week, eg. "20:38:00 135".
time - string (time format) is the 24 hour time of the time to be set for the alarm.
days of the week - string containing the digits representing the days the alarm is to occur on, e.g., Monday, Wednesday and Friday would be "135".
AlarmId - string identifying the alarm
Category - string identifying the alarm category
This effector is only valid on the AGENT:CONFIG event. It enables persistent alarms in the time adapter and provides a file path/name to be used for saving the alarms and other information. Without this effector, the Time Adapter does not save alarms. The following are the file extensions and their uses.
.aln - contains the current file name and extension of the persistent alarms
.al1 and .al2 - contain the persistent alarms
.rec - contains the list of transactions on the set of alarms since the last time they were saved.
.evn - contains the current file name and extension of the event record file
.ev1 and .ev2 - event record files - these contain the time stamp of the alarm time of the last event to complete and any out of order events (ones with later alarm times, but not having had event complete occur yet).
file name - string representing the file path/name of the persistence files
This effector is only valid on the AGENT:CONFIG event. It gives information on handling of duplicate alarms (only non-default identified ones). Handling of duplicates of alarms with default identifiers is described in the time adapter overview. The default is Ignore_Persistent_Duplicates.
a symbol representing how to handle duplicates. The valid symbols are:
Ignore_Duplicates - Ignore but don't set any alarms that are duplicates of currently existing non-default identified alarms.
Flag_Duplicates - Flags and doesn't set any duplicates of non-default identified alarms. Currently this is a message to the terminal.
Ignore_Persistent_Duplicates (default) - Ignores those duplicates of persistent alarms and flags all others.
The default behavior of the time adapter is to present alarms expired within a specified time frame for each interval unit, ie. hours, days, etc. and one-time alarms. These defaults may be overridden with this effector. For example, the overdue alarm presentation criteria for the units of years may be 1 month. This means that any yearly alarms which are set and the start date is within the previous month, the alarm would immediately be presented. For persistent alarms, if the agent has not been running for less than a month, a yearly alarm would be presented when the agent was started, if it would have occurred during the down time. For intervals (non-one time alarms) you can not set the time frame for more than 1 of the criteria interval units. For example, you cannot set the time frame for yearly alarms (or any alarm that has an interval units of years) for 13 months, but you may set it for 12 months. These are the default settings for presentation criteria.
"onetime" - presented if within past 7 days
"years" - presented if within past 7 days
"months" - presented if within past 7 days
"days" - presented if within past 4 hours
"hours" - not presented if expired (set to 0 seconds)
"minutes" - not presented id expired (set to 0 seconds)
"seconds" - not presented if expired (set to 0 seconds) - this cannot be overridden, ie. "seconds" is not a valid string for the first term.
interval units for criteria- one of the following strings: "onetime", "years", "months", "days", "hours", "minutes"
maximum interval value - integer
interval units of maximum interval value - one of the following strings: "years", "months", "days", "hours", "minutes", "seconds"
This effector contains a blank delimited list of those categories to which the persistent alarms belong. Only alarms that are assigned these categories will be saved. If this effector is not used, the "other" category is defaulted to be persistent. The "other" category is the default category assigned to many alarms (see the time adapter overview). If this effector is specified and "other" is to be one of the persistent categories, it must be specified in the list also. This effector has no effect if the setPersistentFileName is not used (persistence is not enabled in this case).
persistent categories - string containing a list (or one) of categories to which the persistent alarms belong
This effector turns off groups of alarms for the selector associated with the conduct set in which it is contained. The string term is a blank delimited list of categories of alarms to turn off.
reset categories - string containing a list (or one) of categories to be reset
This effector tells the time adapter to save the current state of the persistent alarms. The only other time the time adapter will do this is at start and shutdown. Otherwise, the state of the alarms is maintained in a transaction file (.rec) which would need to be reconciled at start. For a continuous running agent, it is advantageous to issue this effector periodically.
Here are a few sample rules, indicating possible ways the trigger events, sensors, and effectors of the time adapter could be used. Note that a rule like "if A and B then C" is written as
(=> (and A B) C)
(=> <antecedent> <consequent>)
To improve readability, some rules have been split across multiple lines. In the run-time environment, each rule is contained entirely on one line.
(=> ( EventName "AGENT:CONFIG" ) ( setPersistentFileName "newalarm"))
(=> ( EventName "AGENT:CONFIG" ) ( setDuplicateHandling Ignore_Duplicates))
(=> ( EventName "AGENT:CONFIG" ) ( setPersistentCategories "persistent special"))
(=> ( EventName "AGENT:CONFIG" ) ( setOverdueAlarmPresentationCriteria "years" 1 "months"))
(=> ( EventName "AGENT:CONFIG" ) ( setOverdueAlarmPresentationCriteria "onetime" 14 "days"))
The utility adapter provides basic functions for terms. It provides basic arithmetic and comparison operations on numbers, conversion operations between integer terms and string terms representing integers. For strings, string append and print operations are provided. For both comparison and arithmetic operations, string operands must represent valid floating point numbers and will be converted to floating point numbers and the appropriate operation will be performed.
The following comparison operators are valid:
The following arithmetic operators are valid:
There is one effector provided:
There are several sensors provide:
None of the information in the eventHeader is pertinent to any sensor in the utility adapter and therefore is ignored. That is, the query answered by each sensor is independent of the event to which this sensor is related.
Given two integers and comparison operator, compares the first term to the third term, and returns a true or false based on the result.
First operand - integer
operator - string representing valid comparison operation
Second operand - integer
Given an integer, a string representing a floating point number, and a comparison operator, compares the first term to the third term, and returns a true or false based on the result.
First operand - integer
operator - string representing valid comparison operation
Second operand - string representing a floating point number
Given a string representing a floating point number, an integer, and a comparison operator, compares the first term to the third term, and returns a true or false based on the result.
First operand - string representing a floating point number
operator - string representing valid comparison operation
Second operand - integer
Given two strings representing floating point numbers and a comparison operator, compares the first term to the third term, and returns a true or false based on the result.
First operand - string representing a floating point number
operator - string representing valid comparison operation
Second operand - string representing a floating point number
Given two real numbers, and a comparison operator, compares the first term to the third term, and returns a true or false based on the result.
First operand - real number
operator - string representing valid comparison operation
Second operand - real number
Given a real number, an integer, and a comparison operator, compares the first term to the third term, and returns a true or false based on the result.
First operand - real number
operator - string representing valid comparison operation
Second operand - integer
Given an integer, a real number, and a comparison operator, compares the first term to the third term, and returns a true or false based on the result.
First operand - an integer
operator - string representing valid comparison operation
Second operand - a real number
Given two integers and arithmetic operator, performs the integer operation on the second and fourth terms, and returns the result in the first term.
Result - integer
First operand - integer
operator - string representing valid arithmetic operation
Second operand - integer
Given a string representing a floating point number, an integer, and an arithmetic operator, performs the floating point operation on the second and fourth terms, and returns the result in the first term.
Result - string representing a floating point number
First operand - string representing a floating point number
operator - string representing valid arithmetic operation
Second operand - integer
Given an integer, a string representing a floating point number, and an arithmetic operator, performs the floating point operation on the second and fourth terms, and returns the result in the first term.
Result - string representing a floating point number
First operand - integer
operator - string representing valid arithmetic operation
Second operand - string representing a floating point number
Given two strings representing a floating point numbers and an arithmetic operator, performs the floating point operation on the second and fourth terms, and returns the result in the first term.
Result - string representing a floating point number
First operand - string representing a floating point number
operator - string representing valid arithmetic operation
Second operand - string representing a floating point number
Given two real numbers and an arithmetic operator, performs the arithmetic operation on the second and fourth terms, and returns the result in the first term.
Result - a real number
First operand - real number
operator - string representing valid arithmetic operation
Second operand - a real number
Given a real number, an integer, and an arithmetic operator, performs the arithmetic operation on the second and fourth terms, and returns the result in the first term.
Result - real number
First operand - real number
operator - string representing valid arithmetic operation
Second operand - an integer
Given an integer, a real number, and an arithmetic operator, performs the arithmetic operation on the second and fourth terms, and returns the result in the first term.
Result - a real number
First operand - an integer
operator - string representing valid arithmetic operation
Second operand - a real number
Given an integer returns a string representing that integer in the first term.
Result - string representing an integer
Number to be converted - integer
Given a string representing an integer returns that value as an integer in the first term.
Result - integer
Number to be converted - a string representing an integer
Given a real number returns a string representing that real number in the first term.
Result - string representing a real number
Number to be converted - a real number
Given a string representing a real number, returns that value as a real number in the first term.
Result - a real number
Number to be converted - a string representing a real number
Given two strings, returns the two strings appended in the first term
Result - string
String 1 - string to which to appended
String 2 - string to be appended
Given eight strings, returns the strings appended in the first term. Can be used to append 3 to 7 strings by using NULL strings ("") in the trailing terms.
Result - string
String 1 - string to which to append
String 2 - first string to be appended
String 3 - second string to be appended
String 4 - third string to be appended
String 5 - fourth string to be appended
String 6 - fifth string to be appended
String 7 - sixth string to be appended
String 8 - seventh string to be appended
String 9 - eighth string to be appended
Output string - string
Here are a few sample rules, indicating possible ways the effectors and sensors of the utility adapter could be used. Note that a rule like "if A and B then C" is written as
(=> (and A B) C)
(=> <antecedent> <consequent>)
To improve readability, some rules have been split across multiple lines. In the run-time environment, each rule is contained entirely on one line.
The Mail adapter is a very basic sample adapter that sends email. It establishes a TCP/IP SMTP (Simple Mail Transfer Protocol) dialog with a relay host to accomplish this (except on OS/2, where it simply invokes the TCP/IP sendmail command instead). It is intended to demonstrate the ability to email data to a user based on rule-based filtering or selection and is not intended to have all the capability of a "well-rounded" email adapter. It is an "effector-only" adapter. That is, it generates no events and has no sensors.
Despite its simplicity, it can provide useful function when linked with an inference engine and other adapters. For example, if used in conjunction with an NNTP adapter it will let you email USENET articles to yourself or others based on whether they match your interests (as specified by rules).
The Mail adapter generates no trigger events. Its domain name is "SampMail".
The Mail adapter has no sensors.
This effector specifies the "From" address which will be used on any subsequent email (for example, "diane@mycompany.com"). If email is sent without the EMailFromAddressIs effector having been run, the "From:" address used will be "user@mymachine.com" where "mymachine.com" is the local host internet address of the machine from which the email is sent. Typically, the user would code a rule to drive this effector on an AGENT:STARTING event, so the "From:" address will be established for all subsequent email.
This effector is not needed on OS/2 or AIX and any use of it on that platform will have no effect (on OS/2 or AIX, the sendmail command is used directly so a relay host need not be specified).
On all other platforms, this effector specifies the relay host (for example, "mycompany.com") to which all subsequent mail sent by the adapter will be forwarded for delivery. After this effector is run, any subsequent calls to the EMail or EMailWithSubject effectors cause a TCP/IP SMTP dialog to be established with the relay host at port 25 (the well-known port number for the SMTP protocol). The email is then sent through this dialog. If email is sent without the EMailRelayHostIs effector having been run, the email effector will fail (that is, mail will not be sent). Typically, the user would code a rule to drive this effector on an Agent:STARTING event, so the relay address will be established for all subsequent email.
EMail the provided text to the provided email address. Typically, the text will have been obtained by some previous sensor call (for example, the NNTP adapter's TextIs sensor to obtain the text of an article).
Just like the EMail effector, but allowing the rule-author to specify a subject line to be added to the email.
Here are some sample rules, indicating possible ways the effectors of the Mail adapter could be used. Note that a rule like "if A and B then C" is written here as
(EMailWithSubject "diane@heraddress" ?x "an article from the silent movie discussion group")
The stock adapter allows fetching of stock quotes from a web site. It is written so that different classes can be written for fetching and parsing the data from different web sites, and the particular classes to fetch the HTML page and to parse it can be specified in the rules. This was written as a sample adapter written in Java to demonstrate all programming interfaces for adapters.
There is one type of Trigger Event generated by this adapter:
There are several utility boolean sensors provided:
One non-boolean sensor is provided:
The following effectors are provided:
This event is presented to the agent after a Stock Monitor has obtained the stock quotes for the given stock symbols. It results from the action of the StockMonitor effector.
This fact provides two terms - strings representing the stock ticker symbol and current price. More than one of these facts may be in the fact set, if more than one stock symbol was given on the StockMonitor effector.
Given two strings representing stock prices and a string representing a comparison operation, performs the arithmetic operation on the two stock prices.
First stock price - string representing a stock price
Operator - string ('=','==','<=','<','>=', or '>')
Second stock price - string representing a stock price
Given two integers and a string representing a comparison operation, performs the arithmetic operation on the two integers.
First integer - an integer value
Operator - string ('=','==','<=','<','>=', or '>')
Second integer - an integer value
Returns a fact with the count of the number of Stock Adapter Events completed.
count - integer representing the number of events completed
This tells the adapter the name of the class to use for the Stock Monitor
Stock monitor Java class name - string
This tells the adapter the name of the class to use for the Stock Parser
Stock parser Java class name - string
This tells the adapter the proxy name and port to use for the Stock Monitor, if a proxy is needed. No proxy will be used if this effector is not called.
Proxy name - string
Port - integer
This displays three strings at the terminal
First string to display
Second string to display
Third string to display
This tells the adapter the URL to use to obtain stock quotes
URL - string
This tells the StockAdapter to fetch quotes for the given stock symbols. It will result in the adapter presenting a StockPriceEvent to the agent.
Stock ticker symbols - string with symbols separated by white space
Here are a few sample rules, indicating possible ways the trigger events, sensors, and effectors of the stock adapter could be used to monitor stock prices. Note that a rule like "if A and B then C" is written as
(=> (and A B) C)
(=> <antecedent> <consequent>)
To improve readability, some rules have been split across multiple lines. In the run-time environment, each rule is contained entirely on one line.
These rules also use the mail and timer adapters. They monitor IBM and LEXMARK stock every 20 minutes for 2 times and then monitor Hershey stock every 20 minutes for 3 times. If IBM is > 100 a message is printed and emailed to the user. If Lexmark stock is > 15 a message is printed. If Hershey stock is > 80 a message is printed and emailed to the user.