Conditional Procedure Example
This example demonstrates how to use event handlers to create a simple
external procedural and SQL interface for doing keyword searches using.
the NYU library's Bobcat catalog system. In some cases,
a keyword search may turn up many results: these are displayed in a recordset.
If only one match is found, Bobcat displays the results using entity
attributes. And if no results are found, yet another entity is displayed.
And Bobcat uses a VT terminal interface.
One interesting aspect of the Bobcat results recordset is that
the records are variable-length, and some fields may or may not be present.
Here are the "rules of recordsets":
A record consists of 1 to 3 lines.
Each record has an index number, a publication date, and a title.
A record may or may not contain an author.
If a record is only one line long, no author will be present.
If a record is two lines long, an author may or may not be present.
An author is present only if the field "looks" like a name
of a person, or if it is marked as a "performer". If an author
is present, one line of title information is supplied, otherwise two lines
of title information appear.
If a record is three lines long, an author is always present, as are
two lines of title information.
The model is fairly simple, but there are some details related to how
recordset event handlers work which are of interest.
The SearchKeywords operation on the Search entity must
list all possible destination entities as primary or alternate. This
allows the SearchByKeyword procedure to do the error checking
after the operation completes.
The SearchResults.Results recordset defines each record as containing
a single line, and all fields are defined to be somewhere on that single line.
parseScreen() event handler will do the work
of locating each record and determining the number of lines it contains.
The fields defined in the Results recordset must be assigned to
specific screen locations in the
parseRecord() event handler.
If no author is present, for example, the event handler places the author field
on a single blank. It does the same with the second title field if no second
line of title information is present.
The job of combining the first and second lines (or fields) of title information
is done by the procedure event handler. This is because each recordset field
must be described by a single offset and length pair. If the title
started on the first line and extended to the second, the publication date would
become part of the title. Therefore the recordset handler returns the title
in pieces, to be reassembled by the recordset event handler before it is
returned to the client.
The implementation of the recordset event handler concerns itself with record parsing.
parseScreen handler uses a simple state machine to find the locations
and sizes of the records. The
parseRecord handler uses the record size
and a pattern matcher to decide whether or not records contain author fields and the
amount of title information provided.
The procedure event handler takes care of validating the search term and issuing
the command to perform the search. It then determines which display screen the
host application displayed in response to the search, and packages the result
in a result recordset.
Execution using the Design Tool
The NYU library is no longer availible for public use. The model can
still be viewed in offline mode in the Design Tool. The following
is a walk through of the host application to aid in understanding
In the exercises that follow, you might consider using the following search terms
to discover how the event handler deals with different situations. Search for
"angioplasty" to generate an empty result set. Search for
"spoonerism" to generate a single result. Search for "tomcat"
to generate a two-page recordset result.
Here is how to invoke the recordset event handler, and to see what it returns
after parsing the records.
Start the Design Tool, open the model, and connect to the NYU library,
and execute the login command list to login to the catalog system.
At the Search entity, execute the SearchKeywords operation.
If you like, you can enter a keyword search command (try
W=zamboni"). This will take you to the
Open the Recordset Test dialog, and press the Execute button. (But if your
search returned more than 100 results, you might want to limit the fetch
size to about 100 records.)
Notice that all results contain a Number, a Title1, and a Year. Those records
which had an author also create a non-blank Author field. Those records which
were three lines long also created a non-blank Title2 field.
Execute the ToSearch operation to return to the Search entity.
Next use the Procedure Test dialog to find out what the procedure event handler
does with what's produced by the recordset handler.
Open the Procedure Test dialog and enter a search term (Keyword) parameter.
Click the Execute button.
After the procedure finishes executing, notice that the two title fields
in the recordset have been combined into one.
Finally, try the SQL Test dialog to display a subset of the columns returned.
Open the SQL Test dialog and enter a SQL statement. To display just the
titles and dates from a search for "zamboni" use
SELECT Title, Date FROM Catalog WHERE Keyword = 'zamboni'.
Click the Resolve button and notice that the statement is resolved into
a call to the Catalog.SearchByKeyword procedure.
Click on the Execute button. The procedure event handler returns the
information requested, but the SQL statement returns only the columns