Variable Recordset Example

Purpose

This example illustrates how to deal with complex, variable-length recordsets, including recordset and field parsing, record classification, and filtering.

The Yale Orbis library system provides an author search function. The output is formatted for ease of use by human readers. On the screen, an author name appears, followed by the books written by that author, and each book's publication date. While no book title record crosses a page boundary, the books published by a single author can appear on multiple pages. In this case the next page will start with the (same) author name, followed by more titles by that author.

To make the data more usable by automated processes, we want to organize the data in a table in which each row contains a book title, the author's first and last names, and the book's publication date.

Implementation

This example attaches the AuthorDetailsRecordsetHandler to the Parse Screen, Parse Record, Get Record Type, and Apply Filter events of the SearchAuthors.AuthorDetails recordset. The example also attaches a MultiBlankFieldHandler to the AuthorDetails.BookName field.

Screen parsing must deal with the fact that while every output record must contain an author name, the author name only appears before the first book for that author. The Parse Record event handler solves this problem by defining overlapping records: each record (where a record is an author name plus a title plus a date) starts with the author name. The first record returned for a particular author contains the author name and one title, the next contains the author name and two titles, and so forth.

Record parsing determines the location of each field within a record. In this case, the author name is taken from the first line of the record. The last title in the record is located, and is used to provide the title and publication date.

A book title can span multiple lines. This introduces the problem of embedded whitespace in the title. Nothing is done about that in the record parsing, but it is dealt with in the BookTitle Read Field event handler.

Some author records do not actually refer to books. These are marked with an asterisk as the first character of the book title. The getRecordType is used to filter these records from the result of a record fetch.

Finally, the applyFilter event is used to filter books based upon their publication date.

Model Design

The model itself is a straightforward 3270 terminal model which uses the Verastream Host Emulator to provide test data.

Execution using the Design Tool

Start by copying the OrbisYaleMaster model into the Verastream models directory so that the Host Emulator can locate it.

Start the Host Emulator Configuration program. Click the Add Model button. Select OrbisYaleMaster from the listbox labeled Name, and set the Port number to 1095. (If 1095 is already used, choose a different one, and be sure to modify the VariableRecordsets model host port number to match.)

Start the Design Tool and open the VariableRecordSets model. Navigate to the SearchDetails entity and open the Recordset Test dialog. Make sure that the AuthorDetails recordset is selected, and that the action is Fetch Records. Press execute. After all of the records are read, they are displayed in the dialog's output window.

To view the diagnostic output produced by the event handlers open the Event Handler Console. The parseScreen event handler writes to the System.out stream when it is called.

To observe how post-fetch filtering works, enter an expression (such as BookDate < 1900) to find all of the items published before 1900. The expressions understood by the filter are of the form BookDate < date, BookDate = date, and BookDate > date