RouteX is a toolkit that allows your program to easily route documents to different destinations based upon specific queries. Each query contains information that RouteX searches documents for. When RouteX finds a document with this information it returns the document and an action to be performed by your application on the document. Because RouteX is a routing toolkit your application is free to take whatever action it desires. For instance you could use RouteX to scan web pages and forward email copies to users based upon the information each user searches for. To aid in maintaining the list of queries RouteX stores a title for each query along with a reference field that can contain whatever information you desire.
The toolkit uses a single object created with rxCreateRouter. This is the router itself and this object is used by most RouteX functions. After you are finished with the router call rxDeleteRouter to free up all the memory that RouteX was using. The list of queries that RouteX uses is stored in a custom database. This database is indexed and allows RouteX to very quickly find specific queries. To start using RouteX you create a database using rxCreateRouterDatabase. After you have a database you can later open it with rxOpenRouterDatabase. You can have multiple databases that you work with, although each RouteX object will only work with a single database at a time. The toolkit contains functions for opening and closing existing databases. To delete a database you can use your typical operating system calls for deleting files.
Each routing session is conducted in a batch. Each batch is made up of a list of documents that are to be routed. Adding a document to a batch consists of three steps: selecting the document, parsing the document, and closing the document.
You select a document to add to the batch by calling rxStartDocument. This tells RouteX that you are working with a new document and stores it's name. The name of the document can be anything your application wishes. If you are routing disk files the name could be the pathname of each file. If you are routing email messages the name might be the mail id of each message. If you are routing news articles the name could be the newsgroup and message id of a particular article. You should choose a name that tells your application enough about the document so that you can find the document when you need to.
After selecting a document you should parse the document. Because RouteX is a toolkit designed to work with any kind of document your application determines how the document should be parsed. RouteX can not parse the document for you. Generally you will go through the document and pass words to RouteX. To feed RouteX a word call rxProcessWord. This adds the word you selected to the internal index that RouteX keeps. Be aware that how you add the word determines how your query is searched. If you wish your routing to be case sensitive make sure you add the words as they are. If you wish to be case insensitive change all words to lower case before calling rxProcessWord.
In addition to simply adding words to RouteX's index, you can also define fields. Fields are ranges of words that have a special name property. For instance you could define an email address field. All words you add to RouteX after starting a field are labeled with this field property. You could then define a query that searches for "email@example.com" in the email address but not in the body of a document. Fields are one of the most powerful features of RouteX as they give you complete control over how documents are searched. It enables you to search not only the body of a document, as with most routers, but also information about a document. For instance you could define fields for author, date, location, or keywords. This gives you incredible flexibility in determining how to route documents. To begin a field call rxStartField. To end a field call rxEndField.
After you've finished parsing a document you must call rxEndDocument. This enables RouteX to update it's index, optimize the file, and prepare to work with a new document. If you wish to add a new document call rxStartDocument again and repeat the above procedure. If you are finished with the batch call rxEndRoutingBatch. When you tell RouteX that you are finished with the batch it will close it's indexes and begin routing the documents. RouteX routes your documents by going through each query you added and searching all the documents in the batch to see which ones match that query. If it finds a document that matches it adds it to a hit list containing the action the query wants performed with the document name.
The most important part of using RouteX is in selecting good queries. Each query consists of a search request, an action, a reference, and a title.
The reference and title information fields are strings that you can use for your own purposes. The title is simply a label for the individual query you are adding. For instance you might have a query titled "Forward Robert's Business Email." You might display this title in a list of queries that you display to the user. The reference can be used for anything your program wishes. For instance if you are routing queries that many users use you may wish to store a user ID in the reference. You can then use the reference field to select and then display only those queries that were created by a specific user. For example we may store the text "Robert" in the reference field. Robert might have three different queries titled "Forward Robert's Business Email", "Save copies of love notes", and "Server error messages". We could then search for Robert in the reference field and the search function will return these three queries whose titles we could display. A different use of the reference field might be to store Robert's email username and password. Your program could then use this to retreive the email messages you route. Both the title and reference fields can be left blank if you don't see a need for them. They are, however, very useful places to store information associated with your routing. RouteX provides functions to search these fields enabling you to organize your queries in very complex ways based upon your needs.
The action is a string representing the action to be performed on any routed document. Once again you can store whatever you wish here. For instance if you are routing disk files to a backup location you might store an OS command to copy the file here. For email routing you might store the email address to forward a message to. You might also simply store some numeric value that your application then uses to determine what action it takes. While the action field can be left blank, you will almost always put something in it.
The search request field is the actual query RouteX uses to search the documents to be routed. See the query language documentation for a list of commands that RouteX supports. Most of the time you will use simply boolean queries. RouteX supports, however, very complex queries that search for document fields, strings, and words near one an other. Unlike some routers RouteX stores its queries in a hexadecimal form. This allows you to route not only English documents but also unicode encoded documents and even binary documents. RouteX provides the function rxConvertQuery to easily convert an ASCII query to its hexadecimal form. If you wish to write your own conversion functions RouteX supplies two functions that convert ASCII characters to and from hexadecimal form.
When you are finished with a batch and have called rxEndRoutingBatch RouteX begins to route the documents. The route processing may take a few moments depending upon the size of the documents in your batch and the number of queries being applied to the batch. To retrieve the routing information call rxGetFirstHit and then rxGetNextHit. These functions return not only the document information but also the query that wants to take an action on the document. For instance you may have two queries that forward news to specific individuals email address. The first query may mail the news article to "firstname.lastname@example.org" while the second query may mail it to "email@example.com". When you call rxGetFirstHit you will get the document information for the news article, say a temporary file holding the article, and then the query information including Bob's email address. Your program then calls a function to email the document. You then call rxGetNextHit and get the same document information but Fred's email address. You then call the function to mail it to Fred. It is important, as we mentioned earlier, to include enough information in your reference and action fields so as to be able to take appropriate action. For instance in the above example we probably would have stored the email address in the reference field and the command "EMAIL" in the action field.