IBM Agent Building Environment Developer's Toolkit


Chapter 5. Adapters Provided by ABE

File Adapter Reference

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.

Trigger Events

FileChanged

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.

Header Information

Domain
File

Type
FileChanged

Fact set

  1. Predicate Name: FileName
    Term: string - The full file name (drive:\path\filename.ext) of the file

  2. Predicate Name: FileSize
    Term: int - The size of the file in bytes

  3. Predicate Name: FileExtension
    Term: string - The file extension (this is defined as the characters following the last period (".") in the file name).

  4. Predicate Name: DirectoryName
    Term: string - The directory (drive and path specification) in which the file resides.

  5. Predicate Name: ShortFileName
    Term: string - The name of the file, minus the drive and path information.
For example, if a "FileChanged" event were being reported for the file "c:\fred\barney\foo.bar" then:

FileCreated

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.

Header Information

Domain
File

Type
FileCreated

Fact set

Same as "FileChanged" (above).

FileDeleted

This event is generated by the File adapter when it detects one of two things:

Header Information

Domain
File

Type
FileDeleted

Fact set

  1. Predicate Name: FileName
    Term: string - The full file name of the file.

  2. Predicate Name: DirectoryName
    Term: string - The path information for the file.

  3. Predicate Name: ShortFileName
    Term: string - The name of the file, minus the drive and path information.
See the section on "FileChanged" for examples of "FileName", "DirectoryName", and "ShortFileName".

FileNotFound

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.

Header Information

Domain
File

Type
FileNotFound

Fact set

Same as "FileDeleted" (above).

CopyFailed

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.

Header Information

Domain
File

Type
CopyFailed

Fact set

Same as "FileDeleted" (above).

MoveFailed

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.

Header Information

Domain
File

Type
MoveFailed

Fact set

Same as "FileDeleted" (above).

DeleteFailed

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.

Header Information

Domain
File

Type
DeleteFailed

Fact set

Same as "FileDeleted" (above).

ExecuteFailed

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.

Header Information

Domain
File

Type
ExecuteFailed

Fact set

Same as "FileDeleted" (above).

FileError

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.

Header Information

Domain
File

Type
FileError

Fact set

Same as "FileDeleted" (above).

AppendFailed

This event is generated by the File adapter when an error occurs during the execution of the "AppendFile" effector.

Header Information

Domain
File

Type
AppendFailed

Fact set

Same as "FileDeleted" (above).

DirectoryEmpty

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.

Header Information

Domain
File

Type
DirectoryEmpty

Fact set

  1. Predicate Name: DirectoryName
    Term: string - The directory path information specified as part of a "CheckDirectory" sensor. See the section on the "CheckDirectory" sensor for more information.

  2. Predicate Name: SearchPattern
    Term: string - The search pattern specified as part of a "CheckDirectory" sensor. See the section on the "CheckDirectory" sensor for more information.

DirectoryError

This event is generated by the File adapter whenever an error is encountered during the execution of "CheckDirectory" sensor.

Header Information

Domain
File

Type
DirectoryError

Fact set

Same as "DirectoryEmpty" (above).

Sensors

ExistFile

Given a full filename (drive:\path\name.ext), this (boolean) sensor returns TRUE if the file exists, and FALSE if it does not.

Terms

FileName, bound, string - The full name of the file whose existence is being tested.

Effectors

CheckFile

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.

Terms

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")

CheckDirectory

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.

Terms

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.

CopyFile

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.

Terms

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")

MoveFile

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.

Terms
Same as "CopyFile" (above).

DeleteFile

A simple effector to delete the specified file. If the file cannot be found, a "FileNotFound" event is generated. Otherwise, no event is generated.

Terms

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.

ExecuteFile

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.

Terms

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".

AppendFile

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.

Terms

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.

Sample Rules

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)

or, more generally

(=> <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:

  1. On agent startup, invoke the Time adapter to set a once-a-day interval alarm..
    (=> (EventName "AGENT:STARTING") (setIntervalAlarm 1440 "minutes") )

  2. When the Time adapter generates the trigger event representing the once-a-day interval alarm, check the directory "d:\lotsuite\wordpro\docs" for any changes to any files matching the search pattern "*.lwp". Because the "ALL" term is specified, a trigger event ("FileCreated", "FileChanged", or "FileDeleted") will be generated for each file that was created, changed or deleted since the last time the directory was checked.
    (=> (and (EventName "Time:IntervalAlarm") (Interval 2 "minutes")) (CheckDirectory "d:\lotsuite\wordpro\docs\" "*.lwp" "ALL") )

  3. When a "FileChanged" trigger event is generated for any of these files, then copy that file to the directory "g:\wordpro\backup". Note that we explicitly test to make sure the trigger event is for a file in the "d:\lotsuite\wordpro\docs" directory -- this prevents us from reacting (perhaps erroneously) to trigger events for files that match "*.lwp" but reside in other directories that are being watched.

    (=> (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) ) )

  4. When a "FileCreated" trigger event is generated for any of these files, then copy that file to the directory "g:\wordpro\backup" (just like Rule 3, but for "FileCreated" trigger events). Note that it is possible to write one giant rule that handles both "FileCreated" and "FileChanged" trigger events, but that would be even more difficult to read!
    (=> (and (and (EventName "File:FileCreated")(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) ) )

  5. When an error is detected in the course of copying one of the files, write a message out to a log file.

    (=> (and (and (EventName "File:CopyFailed")(FileName ?y)) (DirectoryName "d:\lotsuite\wordpro\docs\") ) (AppendFile "g:\wordpro\backup\" "backup.log" "ERROR backing up file" ?y) )

HTTP Adapter Reference

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.

Trigger Events

webPageArrived

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.

Header Information

Domain
HTTP

Type
webPageArrived

Fact set

  1. Predicate Name: URL

    Term: string - URL of the page that was retrieved

  2. Predicate Name: TAG

    Term: string - Title:

    Term: string - value from the Title: header tag, if it exists

  3. Predicate Name: TAG

    Term: string - Content-Type:

    Term: string - value from the Content-Type: header tag, if it exists

  4. Predicate Name: TAG

    Term: string - Content-Length:

    Term: string - value from the Content-Length: header tag, if it exists

  5. Predicate Name: TAG

    Term: string - Last-Modified:

    Term string - value from the Last-Modified: header tag, if it exists

webPageChanged

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.

Header Information

Domain
HTTP

Type
webPageChanged

Fact set

  1. Predicate Name: URL

    Term: string - URL of the page that has changed

  2. Predicate Name: TAG

    Term: string - Title:

    Term: string - value from the Title: header tag, if it exists

  3. Predicate Name: TAG

    Term: string - Content-Type:

    Term: string - value from the Content-Type: header tag, if it exists

  4. Predicate Name: TAG

    Term: string - Content-Length:

    Term: string - value from the Content-Length: header tag, if it exists

  5. Predicate Name: TAG

    Term: string - Last-Modified:

    Term: string - value from the Last-Modified: header tag, if it exists

addFailed

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.

Header Information

Domain
HTTP

Type
addFailed

Fact set

  1. Predicate Name: URL

    Term: string - URL of the page that was not added to the monitor list

  2. Predicate Name: ErrorMsg

    Term: string - Brief message containing the reason the add failed.

Sensors

All HTTP adapter sensors ignore the event header selector.

GetHTTPStream

Returns all of the data that was returned from the HTTP Get request. This includes the HTTP header and the content.

Terms

Buffer, free, string - a variable into which the stream data will be 'placed'

GetHTTPContent

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).

Terms

Buffer, free, string - a variable into which the data will be 'placed'

TagValue

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.

Terms

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.

Effectors

All HTTP adapter effectors ignore the event header selector.

SetHTTPProxy

This effector establishes the proxy server that should be used by the adapter for web communications.

Terms

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.

Notes

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

SetHTTPSocks

This effector establishes the socks server that should be used by the adapter for web communications.

Terms

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.

Notes

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

RequestHTTPWebPage

This effector will retrieve a page from the web. When the page arrives, it will generate a webPageArrived trigger event.

Terms

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).

AddURLtoMonitorList

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.

Terms

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).

AddURLtoMonitorList2

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.

Terms

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.

Valid symbol values are:

ForceAdd
Add the page to the monitor list in spite of the error.

Note that this will cause a webPageChanged event the first time the page is successfully retrieved from the web on a CheckMonitoredPagesForChanges effector.

GenerateEvent
Generate an addFailed event if an error occurs, and do not add the URL to the monitor list.

RemoveURLfromMonitorList

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.

Terms

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.

CheckMonitoredPagesForChanges

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.

Terms

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.

Sample Rules

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)

or, more generally

(=> <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.

  1. On agent startup, enable the adapter to communicate with the web. The rule can do this in one of four ways:
    Using a socks server on the default port (1080),
    (=> (EventName "AGENT:STARTING") (SetHTTPSocks "socks.location.com"))
    or using a socks server on a specific port (1088),
    (=> (EventName "AGENT:STARTING") (SetHTTPSocks "socks.location.com:1088"))
    or using a proxy server on the default port (80),
    (=> (EventName "AGENT:STARTING") (SetHTTPProxy "http://proxy.location.com/"))
    or using a proxy server on a specific port (88).
    (=> (EventName "AGENT:STARTING") (SetHTTPProxy "http://proxy.location.com:88/"))

  2. On agent startup, ask for a page from the web
    (=> (EventName "AGENT:STARTING") (RequestHTTPWebPage "http://www.ibm.com/"))

  3. When a web page arrives, get its URL and, if the page was successfully received and is an HTML page, then add the page to the monitor list for subsequent monitoring.
    (=> (AND (EventName "HTTP:webPageArrived") (AND (URL ?u) (AND (TagValue "Response-Code:" "200") (TagValue "Content-Type:" "text/html")))) (AddURLtoMonitorList ?u))

  4. When a web page arrives, get its URL and, if the page has been permanently moved (as indicated by the response code), then remove the page's current URL from the monitor list and add it's new url to the monitor list.
    (=> (AND (EventName "HTTP:webPageArrived") (AND (URL ?u) (AND (TagValue "Response-Code:" "301") (TagValue "Location:" ?n)))) (AND (RemoveURLfromMonitorList ?u) (AddURLtoMonitorList ?n)))

  5. On agent startup, use the time adapter to set an alarm that will trigger an event every two hours. We will use this event to check the pages on our monitor list for changes.
    (=> (EventName "AGENT:STARTING") (setIdentifiedIntervalAlarm "CheckPages" 120 "minutes"))

  6. When the "CheckPages" alarm goes off, check all the pages on the monitored-pages list to see if any of them have changed.
    (=> (AND (EventName "Time:IdentifiedAlarm") (AlarmId "CheckPages")) (CheckMonitoredPagesForChanges ""))

  7. When a page that is being monitored for changes reports that a change has occurred, get the content of the changed web page and send it to the specified Email address (using the sample email adapter).
    (=> (AND (EventName "HTTP:webPageChanged") (GetHTTPContent ?c)) (EMail "me@my.loc.com" ?c))

NNTP Adapter Reference

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.

Trigger Events

NEW_NEWS

This event is generated by the NNTP adapter when it has successfully retrieved an article from a USENET newsgroup.

Header Information

Domain
NNTP

Type
NEW_NEWS

Fact set

  1. Predicate Name: FromGroup
    Term: string - The name of the newsgroup from which the article was retrieved.

Sensors

KeyInBody

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).

Terms
Phrase, bound, string - The phrase to search for.
CaseSensitive, bound, integer - 1 indicates string comparisons are case-sensitive, 0 indicates they are not.

KeyInHeader

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.

Terms
HeaderFieldName, bound, string - The header field to check ("subject", "organization", etc.).
Phrase, bound, string - The phrase to search for.
CaseSensitive, bound, integer - 1 indicates string comparisons are case-sensitive, 0 indicates they are not.

IsFrom

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.

Terms
Name, bound, string - Name to check for.
CaseSensitive, bound, integer - 1 indicates string comparisons are case-sensitive, 0 indicates they are not.

IsFromEmailAddress

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.

Terms
EMailAddress, bound, string - The email address to check for.

InGroup

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).

Terms
Newsgroup, bound, string - Newsgroup to check for, with trailing asterisk if desired.

IsUuencoded

Determines if the article contains uuencoded data.

Terms
Token, bound, string - This term can be any string. To prevent the IsUuencoded sensor from having to be run more than once on a given event, be sure to use the same string for this term in all your rules involving isUuencoded. (Future versions should eliminate the need to specify this placeholder string).

IsMime

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").

Terms
ContentType,bound, string - MIME content-type to check for, specified as described above.

LinesInRange

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.

Terms
Minimum, bound, integer - Minimum number of lines the article must have.
Maximum, bound, integer - Maximum number of lines the article may have.

TextIs

Used to sense the entire contents of the article (header and body).

Terms
Text, free, string - Text of the article.

Effectors

SelectHistoryFile

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.

Terms
HistoryFileName, bound, string - The filename of the history file. An extension of ".hst" will be added automatically so no extension should be provided here.
ServerName, bound, string - The host name or IP address of the USENET news server from which to retrieve articles.
PortNumber, bound, integer - The port number on which to connect to the news server (typically 119).

AddNewsgroup

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.

Terms
Newsgroup, bound, string - The name of the newsgroup, including a trailing asterisk if desired.

GetNews

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).

Terms
Token, bound, string - This term can be any string. To prevent the GetNews effector from being run more than once on a given event, be sure to use the same string for this term in all your rules involving GetNews. (Future versions should eliminate the need to specify this placeholder string).

Show

A simple effector to display an article to standard output. This effector is useful for testing rules.

Terms
Description, bound, string - A string containing descriptive information; it is sent to standard output before the second term. Typically this is a string describing why the Show effector has been driven (for example, "This article seems to be about mountain biking, which your rules say you are interested in:").
Article, bound, string - A string containing information to display to standard output; typically this is the article text as previously retrieved by a TextIs sensor call, but it may be any string.

Sample 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

(=> (and A B) C)
or, more generally
(=> <antecedent> <consequent>)

  1. On agent startup, select a history file and news server:
    (=> (EventName "AGENT:STARTING") (SelectHistoryFile "myfile" "newserv.farbercoll.com" 119))

  2. On agent startup, select some newsgroups to forage:
    (=> (EventName "AGENT:STARTING") (AddNewsgroup "comp.lang.smalltalk"))
    (=> (EventName "AGENT:STARTING") (AddNewsgroup "comp.lang.java"))
    (=> (EventName "AGENT:STARTING") (AddNewsgroup "rec.arts.movies.reviews"))

  3. On agent startup, setup an alarm to go off every 4 hours. Use this alarm to signal a forage for new news. Note that the "setIntervalAlarm" effector and the "Time:IntervalAlarm" trigger event with associated "Interval" predicate are all part of a Time adapter, not the NNTP adapter:

    (=> (EventName "AGENT:STARTING") (setIntervalAlarm 240 "minutes"))

    (=> (and (EventName "Time:IntervalAlarm")(Interval 240 "minutes")) (GetNews "token"))

  4. For each new article, if the subject contains the phrase "garbage collection" (in any mixture of upper and lower case) and comes from a group in USENET's "comp.lang.*" hierarchy, then email me the article. Note that the "EMail" effector is part of an EMail adapter, not the NNTP adapter; alternatively, you could use the NNTP adapter's "Show" effector here to send the article to standard output rather than emailing it. Also, note that the "About" predicate is one created by the rules author (it is not associated with any particular adapter). The term "?x" is a variable; in this example it may be bound (by the "TextIs" sensor) to the text of the article so that that text can be used by the "EMail" effector.

    (=> (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))

Time Adapter Reference

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:

Trigger Events

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.

Alarm

The Time Adapter presents only one type of event. This event is a timer event that results from setting an alarm.

Event Header Information

Domain
Time

Type
Alarm

Fact set

  1. Predicate Name: AlarmTime

    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.

  2. Predicate Name: DayOfWeek

    This fact provides one term - an integer representing the day of the week.

  3. Predicate Name: AlarmId

    This has one term, a string, which is the identifier of the alarm.

  4. Predicate Name: AlarmCategory

    This has one term, a string, which is the category of the alarm.

  5. Predicate Name: IntervalsMissed

    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.

  6. Predicate Name: Interval

    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".

  7. Predicate Name: Remainder

    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.

Sensors

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.

timeAfter

Given two date and times, answers true if the first is after the second.

4 Terms - all bound

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

timeBefore

Given two date and times, answers true if the first is before the second.

4 Terms - all bound

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

currentTimeAfter

Given a date and time, answers true if the current time is after the given one.

2 Terms - all bound

date - string (date format) is the date

time - string (time format) is the 24 hour time

currentTimeBefore

Given a date and time, answers true if the current time is before the given one.

2 Terms - all bound

date - string (date format) is the date

time - string (time format) is the 24 hour time

timeBetween

Given three date and times, answers true if the second is between the first and the third.

6 Terms - all bound

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

currentTimeBetween

Given two date and times, answers true if the current time is between the first and the second.

4 Terms - all bound

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

timeEqual

Given two date and times, answers true if they are equal.

4 Terms - all bound

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

timeNotEqual -

Given two date and times, answers true if they are not equal.

4 Terms - all bound

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

currentTimeEqual

Given a date and time, answers true if they are equal to the current time.

2 Terms - all bound

date - string (date format) is the date

time - string (time format) is the 24 hour time

currentTimeNotEqual

Given a date and time, answers true if they are not equal to the current time.

2 Terms - all bound

date - string (date format) is the date

time - string (time format) is the 24 hour time

isCurrentDay

Given a digit representing a day of the week, answers true if it matches the current day of the week.

1 Term - bound

weekday - String

isWeekend

Given a digit representing a day of the week, answers true if it is day 0 or 6.

1 Term - bound

weekday - String

isCurrentWeekday

Answers true if the current day of the week is 1-5.

1 Term - bound

a symbol=True

isCurrentWeekend

Answers true if the current day of the week is 0 or 6.

1 Term - bound

a symbol=True

dateAndTime

Returns the current date and time

2 Terms - free

date - string (date format) is the date

time - string (time format) is the 24 hour time

currentDate

Returns the current date

1 Term - free

date - string (date format) is the date

currentTime

Returns the current time

1 Term - free

time - string (time format) is the 24 hour time

dayOfWeek

Returns the current day of the Week

1 Term - free

day of Week - String (0, 1, 2, 3, 4, 5, or 6)

addTimeInterval

adds a given interval to a date and time and returns a date and time

6 Terms - first four are bound, terms 5 and 6 are free

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

determineTimeInterval

Takes two date and times and determines the interval between the two

5 Terms - first four are bound, term 5 is free

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

Effectors

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.

turnOffAlarm

This turns off an alarm. It is matched only by the alarm identifier.

1 term

AlarmId - string identifying the alarm to turn off

setAlarmAt

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".

4 terms

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

setIntervalAlarm

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".

4 terms

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

setStartBoundedIntervalAlarm

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".

6 terms

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

setEndBoundedIntervalAlarm

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".

6 terms

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

setBoundedIntervalAlarm

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".

8 terms

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

setIntervalAlarmRandomStart

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.

5 terms

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

setRandomStartBoundedIntervalAlarm

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.

7 terms

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

setRandomBoundedIntervalAlarm

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.

9 terms

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

setDailyAlarm

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".

3 terms

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

setSpecificDailyAlarm

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".

4 terms

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

setPersistentFileName

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).

1 term

file name - string representing the file path/name of the persistence files

setDuplicateHandling

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.

1 term

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.

setOverdueAlarmPresentationCriteria

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.

3 terms

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"

setPersistentCategories

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).

1 term

persistent categories - string containing a list (or one) of categories to which the persistent alarms belong

reset

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.

1 term

reset categories - string containing a list (or one) of categories to be reset

checkPoint

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.

0 terms

Sample rules

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)

or, more generally

(=> <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.

  1. Sample rule to set an alarm for 30 minutes after agent start
    (=> (AND (AND ( EventName "AGENT:STARTING" ) ( EventTime ?d ?t ) ) ( addTimeInterval ?d ?t 30 "minutes" ?nd ?nt ) ) ( setAlarmAt ?nd ?nt "30 minute" "") )

  2. Sample rules for setting a 12 minute interval alarm and performing some action (GetNews) when that alarm occurs
    1. (=> ( EventName "AGENT:STARTING" ) ( setIntervalAlarm 12 "minutes" "12 minute" "" ) )
    2. (=> (AND ( EventName "Time:Alarm" ) ( AlarmId "12 minute" ) ) ( GetNews "token" ) )

  3. Sample rule to set a bounded interval alarm of 10 minutes starting 30 minutes after agent start and ending 60 minutes after agent start
    (=> (AND (AND (AND ( EventName "AGENT:STARTING" ) ( EventTime ?d ?t ) ) ( addTimeInterval ?d ?t 30 "minutes" ?sd ?st ) ) ( addTimeInterval ?d ?t 60 "minutes" ?ed ?et ) ) ( setBoundedIntervalAlarm 10 "minutes" ?sd ?st ?ed ?et "BoundedInterval" "" ) )

  4. Sample rules to set an interval alarm and perform a GetNews and also turn off the alarm when the alarm occurs
    1. (=> ( EventName "AGENT:STARTING" ) ( setIntervalAlarm 55 "minutes" "55 minute Interval" "") )
    2. (=> (AND ( EventName "Time:Alarm" ) ( AlarmId "55 minute Interval" )) (AND ( turnOffAlarm "55 minute Interval" ) ( GetNews "token" ) ))

  5. Sample rules to execute GetNews effector every 1 hour between 08:00:00 and 22:00:00 and every 3 hours between 22:00:00 and 08:00:00 (doesn't include NNTP adapter set up rules)
    1. On agent startup, set alarm to go off at 8:00am every day.
      (=> (EventName "AGENT:STARTING") (setDailyAlarm "08:00:00" "AM Alarm" "") )
    2. On agent startup, set alarm to go off at 10:00pm every day.
      (=> (EventName "AGENT:STARTING") (setDailyAlarm "22:00:00" "PM Alarm" "") )
    3. On agent startup, if startup time is between 8am and 10pm then set an alarm to go off every hour and call the alarm "GetNewsDayTime".
      (=> (AND (AND (EventName "AGENT:STARTING") (EventTime ?d ?t)) (timeBetween ?d "08:00:00" ?d ?t ?d "22:00:00")) (setIntervalAlarm 60 "minutes" "GetNewsDayTime" "") )
    4. On agent startup, if startup time is before 8am then set an alarm to go off every 3 hours and call the alarm "GetNewsNiteTime".
      (=> (AND (AND (EventName "AGENT:STARTING") (EventTime ?d ?t)) (timeBefore ?d ?t ?d "08:00:00")) (setIntervalAlarm 180 "minutes" "GetNewsNiteTime" "") )
    5. On agent startup, if startup time is after 10pm then set an alarm to go off every 3 hours and call the alarm "GetNewsNiteTime".
      (=> (AND (AND (EventName "AGENT:STARTING") (EventTime ?d ?t)) (timeAfter ?d ?t ?d "22:00:00")) (setIntervalAlarm 180 "minutes" "GetNewsNiteTime" "") )
    6. When the 8am daily alarm goes off, turn off the alarm called "GetNewsNiteTime" and turn on the hourly "GetNewsDayTime" alarm.
      (=> (AND (EventName "Time:Alarm")(AlarmId "AM Alarm")) (AND (turnOffAlarm "GetNewsNiteTime") (setIntervalAlarm 60 "minutes" "GetNewsDayTime" "")) )
    7. When the 10pm daily alarm goes off, turn off the alarm called "GetNewsDayTime" and turn on the "GetNewsNiteTime" alarm.
      (=> (AND (EventName "Time:Alarm")(AlarmId "PM Alarm")) (AND (turnOffAlarm "GetNewsDayTime") (setIntervalAlarm 180 "minutes" "GetNewsNiteTime" "")) )
    8. When the "GetNewsDayTime" alarm goes off, tell the NNTP adapter to go get news.
      (=> (AND (EventName "Time:Alarm") (AlarmId "GetNewsDayTime")) (GetNews "token") )
    9. When the "GetNewsNiteTime" alarm goes off, tell the NNTP adapter to go get news.
      (=> (AND (EventName "Time:Alarm") (AlarmId "GetNewsNiteTime")) (GetNews "token") )

  6. Sample rules to execute checkPoint effector at 3AM every day.
    1. (=> (EventName "AGENT:STARTING") (setDailyAlarm "03:00:00" "checkPoint" ""))
    2. (=> (AND (EventName "Time:Alarm") (AlarmId "checkPoint")) (checkPoint))

  7. Sample rule to reset all alarms in the "init" and "special" categories for the selector associated with the conduct set that contains this rule.
    1. (=> ( EventName "AGENT:CSCHANGE" ) ( reset "init special"))

  8. Sample rules to set up persistence - these would be in a conduct set with AGENT_CONFIG as the associated selector.
    1. Set up the filename of the persistence files to be "newalarm" in the current directory.

      (=> ( EventName "AGENT:CONFIG" ) ( setPersistentFileName "newalarm"))

    2. Set the duplicate handling to ignore (and not set) all duplicate alarms with no message.

      (=> ( EventName "AGENT:CONFIG" ) ( setDuplicateHandling Ignore_Duplicates))

    3. Set the persistent categories to be "persistent" and "special". Now only those alarms that have the category specified as "persistent" or "special" will be saved.

      (=> ( EventName "AGENT:CONFIG" ) ( setPersistentCategories "persistent special"))

    4. Override the default alarm expiration criteria for one-time alarms and for yearly alarms. Now, yearly alarms that were to occur in the past month, but have not been presented yet (probably, because the agent wasn't running) and one-time alarms that were to occur in the last 14 days but have not been presented yet will be presented when the agent starts. One-time and yearly alarms older than this will be discarded.

      (=> ( EventName "AGENT:CONFIG" ) ( setOverdueAlarmPresentationCriteria "years" 1 "months"))

      (=> ( EventName "AGENT:CONFIG" ) ( setOverdueAlarmPresentationCriteria "onetime" 14 "days"))

Utility Adapter Reference

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:

==
equal

!=
not equal

<
less than

<=
less than or equal

>
greater than

>=
greater than or equal

The following arithmetic operators are valid:

+
add

-
subtract

*
multiplication

/
division

%
mod (only valid for integer to integer operations)

There is one effector provided:

There are several sensors provide:

Sensors

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.

CompareI2I

Given two integers and comparison operator, compares the first term to the third term, and returns a true or false based on the result.

3 Terms - all bound

First operand - integer

operator - string representing valid comparison operation

Second operand - integer

CompareI2S

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.

3 Terms - all bound

First operand - integer

operator - string representing valid comparison operation

Second operand - string representing a floating point number

CompareS2I

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.

3 Terms - all bound

First operand - string representing a floating point number

operator - string representing valid comparison operation

Second operand - integer

CompareS2S

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.

3 Terms - all bound

First operand - string representing a floating point number

operator - string representing valid comparison operation

Second operand - string representing a floating point number

CompareR2R

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.

3 Terms - all bound

First operand - real number

operator - string representing valid comparison operation

Second operand - real number

CompareR2I

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.

3 Terms - all bound

First operand - real number

operator - string representing valid comparison operation

Second operand - integer

CompareI2R

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.

3 Terms - all bound

First operand - an integer

operator - string representing valid comparison operation

Second operand - a real number

MathI2I

Given two integers and arithmetic operator, performs the integer operation on the second and fourth terms, and returns the result in the first term.

4 Terms - first is free, the last three are bound

Result - integer

First operand - integer

operator - string representing valid arithmetic operation

Second operand - integer

MathS2I

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.

4 Terms - first is free, the last three are bound

Result - string representing a floating point number

First operand - string representing a floating point number

operator - string representing valid arithmetic operation

Second operand - integer

MathI2S

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.

4 Terms - first is free, the last three are bound

Result - string representing a floating point number

First operand - integer

operator - string representing valid arithmetic operation

Second operand - string representing a floating point number

MathS2S

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.

4 Terms - first is free, the last three are bound

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

MathR2R

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.

4 Terms - first is free, the last three are bound

Result - a real number

First operand - real number

operator - string representing valid arithmetic operation

Second operand - a real number

MathR2I

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.

4 Terms - first is free, the last three are bound

Result - real number

First operand - real number

operator - string representing valid arithmetic operation

Second operand - an integer

MathI2R

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.

4 Terms - first is free, the last three are bound

Result - a real number

First operand - an integer

operator - string representing valid arithmetic operation

Second operand - a real number

ConvertI2S

Given an integer returns a string representing that integer in the first term.

2 Terms - first is free, the second is bound

Result - string representing an integer

Number to be converted - integer

ConvertS2I

Given a string representing an integer returns that value as an integer in the first term.

2 Terms - first is free, the second is bound

Result - integer

Number to be converted - a string representing an integer

ConvertR2S

Given a real number returns a string representing that real number in the first term.

2 Terms - first is free, the second is bound

Result - string representing a real number

Number to be converted - a real number

ConvertS2R

Given a string representing a real number, returns that value as a real number in the first term.

2 Terms - first is free, the second is bound

Result - a real number

Number to be converted - a string representing a real number

StringAppend

Given two strings, returns the two strings appended in the first term

3 Terms - first is free, the second and third are bound

Result - string

String 1 - string to which to appended

String 2 - string to be appended

StringAppendMany

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.

9 Terms - first is free, the second thru ninth are bound

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

Effector

StringPrint
Prints out the string given with a new line on the end.

1 terms

Output string - string

Sample rules

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)

or, more generally

(=> <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.

  1. Sample rule to print a string
    (=> ( EventName "AGENT:STARTING" ) ( StringPrint "Test string!" ) )

  2. Sample rule to append strings (two at a time)
    (=> (AND (AND (AND (AND ( EventName "AGENT:STARTING" ) ( EventTime ?d ?t) ) ( StringAppend ?var1 "Agent Starting: " ?d ) ) ( StringAppend ?var2 ?var1 " " ) ) ( StringAppend ?var3 ?var2 ?t ) ) ( StringPrint ?var3 ) )

  3. Sample rule to append four strings together
    (=> (AND (AND (AND (AND ( EventName "AGENT:STARTING" ) ( EventTime ?d ?t) ) ( StringAppendMany ?var1 "Agent Starting: " ?d " " ?t "" "" "" "") ) ( StringPrint ?var1 ) )

  4. Sample rule to convert a string to an integer then add two integers and convert the result to a string so it can be appended to a message and outputted
    (=> (AND (AND (AND (AND ( EventName "AGENT:STARTING" ) ( ConvertS2I ?intvar "100" ) ) ( MathI2I ?result ?intvar "+" 1 ) ) ( ConvertI2S ?strresult ?result ) ) ( StringAppend ?final "Result: " ?strresult ) ) ( StringPrint ?final ) )

  5. Sample rule to add two floats represented as strings and output the result
    (=> (AND (AND ( EventName "AGENT:STARTING" ) ( MathS2S ?var "125.25" "+" ".25" ) ) ( StringAppend ?fvar "125.25+.25=" ?var ) ) ( StringPrint ?fvar ) )

  6. Sample rule to add a real number to and integer and output the result
    (=> (AND (AND (AND ( EventName "AGENT:STARTING" ) ( MathR2I ?var 125.25 "+" 14 ) ) ( ConvertR2S ?svar ?var ) ) ( StringAppend ?fvar "125.25+.25=" ?svar ) ) ( StringPrint ?fvar ) )

  7. Sample rule to compare integer to float represented as string and output message
    (=> (AND ( EventName "AGENT:STARTING" ) ( CompareI2S 100 "<" "125.25" ) ) ( StringPrint "The float value is > 100" ) )

Mail (Sample) Adapter Reference

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).

Trigger Events

The Mail adapter generates no trigger events. Its domain name is "SampMail".

Sensors

The Mail adapter has no sensors.

Effectors

EMailFromAddressIs

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.

Terms
FromAddress, bound, string - The "From:" address, in the format "user@hostname".

EMailRelayHostIs

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.

Terms
RelayHost, bound, string - The relay host name, for example "mycompany.com".

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).

Terms
ToAddress, bound, string - The address to send the email to, in the format "user@hostname".
Text, bound, string - The text to email.

EMailWithSubject

Just like the EMail effector, but allowing the rule-author to specify a subject line to be added to the email.

Terms
ToAddress, bound, string - The address to send the email to, in the format "user@hostname".
Text, bound, string - The text to email.
Subject, bound, string - Some "Subject:" text to add to the email header.

Sample Rules

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

(=> (and A B) C)
or, more generally
(=> <antecedent> <consequent>)

  1. On agent startup, select a "From:" address:
    (=> (EventName "AGENT:STARTING") (EMailFromAddressIs "me@myaddress"))

  2. On agent startup, select a relay host name (a rule like this is not needed on OS/2, although it would have no ill effects):
    (=> (EventName "AGENT:STARTING") (EMailRelayHostIs "mycompany.com"))

  3. Email Diane all USENET articles that have been foraged from the newsgroup "alt.movies.silent". Note that FromGroup and TextIs are associated with an NNTP adapter, not the Mail adapter.
    (=> (and (FromGroup "alt.movies.silent") (TextIs ?x)) (EMail "diane@heraddress" ?x))
    An alternative to the EMail effector usage here would be

    (EMailWithSubject "diane@heraddress" ?x "an article from the silent movie discussion group")

Stock (Sample) Adapter Reference

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:

Trigger Events

StockPriceEvent

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.

Event Header Information

Domain
StockAdapter

Type
StockPriceEvent

Fact set

  1. Predicate Name: StockPrice

    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.

Sensors

StockCompare

Given two strings representing stock prices and a string representing a comparison operation, performs the arithmetic operation on the two stock prices.

3 Terms - all bound

First stock price - string representing a stock price

Operator - string ('=','==','<=','<','>=', or '>')

Second stock price - string representing a stock price

IntegerCompare

Given two integers and a string representing a comparison operation, performs the arithmetic operation on the two integers.

3 Terms - all bound

First integer - an integer value

Operator - string ('=','==','<=','<','>=', or '>')

Second integer - an integer value

GetStockEventCount

Returns a fact with the count of the number of Stock Adapter Events completed.

1 Term - free

count - integer representing the number of events completed

Effectors

StockAdapterMonitorClass

This tells the adapter the name of the class to use for the Stock Monitor

1 term

Stock monitor Java class name - string

StockAdapterParserClass

This tells the adapter the name of the class to use for the Stock Parser

1 term

Stock parser Java class name - string

StockAdapterProxy

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.

2 terms

Proxy name - string

Port - integer

StockAdapterShow

This displays three strings at the terminal

3 terms

First string to display

Second string to display

Third string to display

StockAdapterURL

This tells the adapter the URL to use to obtain stock quotes

1 term

URL - string

StockMonitor

This tells the StockAdapter to fetch quotes for the given stock symbols. It will result in the adapter presenting a StockPriceEvent to the agent.

1 terms

Stock ticker symbols - string with symbols separated by white space

Sample rules

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)

or, more generally

(=> <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.

  1. On agent startup, tell the stock adapter which java class to use to obtain the stock quotes.
    (=> (EventName "AGENT:STARTING") (StockAdapterMonitorClass "ibm.AgentBuilder.samples.stock.QuoteYahooCom"))

  2. On agent startup, tell the stock adapter which url to use to obtain the stock quotes.
    (=> (EventName "AGENT:STARTING") (StockAdapterURL "quote.yahoo.com/quotes"))

  3. On agent startup, tell the stock adapter which java class to use to parse the data that comes back from the stock price web page.
    (=> (EventName "AGENT:STARTING") (StockAdapterParserClass "ibm.AgentBuilder.samples.stock.ParseQuoteYahooCom"))

  4. On agent startup, tell the stock adapter which proxy server to use to access the web
    (=> (EventName "AGENT:STARTING") (StockAdapterProxy "xxx.xxx.xxx.xxx" 8088))

  5. On agent startup, tell the sample email adapter what email address to use as the 'from' address on any mail that it sends.
    (=> (EventName "AGENT:STARTING") (EMailFromAddressIs "user@address.xxx.xxx.xxx"))

  6. On agent startup, use the time adapter set an alarm to go off every 20 minutes. Call the alarm "IBM LXK" (so later we can use the alarm id to tell the stock adapter to get prices for IBM and LexMark stock)
    (=> (EventName "AGENT:STARTING") (SetIdentifiedIntervalAlarm "IBM LXK" 20 "minutes"))

  7. When an alarm triggers, tell the stock adapter to go check stock prices. Use the alarmid to tell the stock adapter which stocks to check.
    (=> (AND (EventName "Time:IdentifiedAlarm") (AlarmId ?alarmId)) (StockMonitor ?alarmId))

  8. When the stock adapter triggers an event indicating that it has a stock price available, if the price is for IBM stock and it's above $100, then display a message and send an email to notify someone.
    (=> (AND (AND (EventName "StockAdapter:StockPriceEvent") (StockPrice "IBM" ?price)) (StockCompare ?price ">" "100.0")) (AND (StockAdapterShow "IBM stock is above 100! " ?price " I sent email.") (EMail "user@xxx.xxx.xxx" "IBM stock is above 100!")))

  9. When the stock adapter triggers an event indicating that it has a stock price available, if the price is for LexMark stock and it's above $15, then display a message.
    (=> (AND (AND (EventName "StockAdapter:StockPriceEvent") (StockPrice "LXK" ?price )) (StockCompare ?price ">" "15.0")) (StockAdapterShow "LexMark stock is above 15! " ?price "I didn't send email."))

  10. When the stock adapter triggers an event indicating that it has a stock price available, and this is the second such event (as counted by the stock adapter and provided through GetStockEventCount), then turn off the "IBM LXK" alarm and turn on a 20 minute alarm for "HSY" (Hershey) stock monitoring. Also, display some messages to say what we are doing.
    (=> (AND (AND (EventName "StockAdapter:StockPriceEvent") (GetStockEventCount ?count)) (IntegerCompare ?count "=" 2)) (AND (AND (AND (TurnOffIdentifiedIntervalAlarm "IBM LXK") (StockAdapterShow "I just turned off the primary alarm." " " " ")) (SetIdentifiedIntervalAlarm "HSY" 20 "minutes")) (StockAdapterShow "I just started an interval alarm for Hershey foods" " " " ")))

  11. When the stock adapter triggers an event indicating that it has a stock price available, if the price is for Hershey stock and it's above $80, then display a message and send an email to notify someone.
    (=> (AND (AND (EventName "StockAdapter:StockPriceEvent") (StockPrice "HSY" ?price)) (StockCompare ?price ">" "80.0" )) (AND (StockAdapterShow "Hershey stock is above 80! " ?price " I sent Email.") (EMail "user@xxx.xxx.xxx" "Hershey stock is above 80.0!")))

  12. When the stock adapter triggers an event indicating that it has a stock price available, and this is the sixth or more such event (as counted by the stock adapter and provided through GetStockEventCount), then turn off the "HSY" alarm and display a message.
    (=> (AND (AND (EventName "StockAdapter:StockPriceEvent") (GetStockEventCount ?count)) (IntegerCompare ?count ">" 5)) (AND (TurnOffIdentifiedIntervalAlarm "HSY") (StockAdapterShow "I just turned off the secondary alarm." " " " ")))


[ Top of Page | Previous Page | Table of Contents ]