1.5 Result-set collections

1.5.4 Liaison functions

Liaison functions convert records retrieved from a database query to Dylan objects. These functions bridge the conceptual gap between relational databases and Dylan's object-orientation.

To create a Dylan object from a retrieved record, the liaison function must understand the form of the records coming from the database and the mappings of records to Dylan objects. These Dylan objects make up the elements of the result set: the results of the liaison function are added to the result set each time it is called. As your application iterates over a result set, the liaison function provides the objects that the application processes.

If you do not provide a liaison function for a result set, the SQL-ODBC library supplies a default-liaison function to perform the conversion. If a coercion policy is provided, the default-liaison function is copy-sequence. The new sequence is safe in that it is a normal Dylan collection with no relationship to databases, SQL statements, or result sets. If a coercion policy is not provided, the default-liaison is the identity function.

You can specify the identity function as the liaison function to process the actual record objects. If no type coercion is performed by the functions on the record class, this function will have the lowest overhead, but there are some restrictions: the values retrieved from the record may become invalid when the state of the iteration protocol changes.

The liaison function can, potentially, cause the greatest number of problems for an application using SQL-ODBC since there is no type safety between the liaison function, the record class and the SQL SELECT statement. You must ensure that the liaison function is in sync with the SQL SELECT statement since there is no support in SQL-ODBC for this.

Example:

define class <book> (<object>)
  slot title :: <string>, init-keyword: title:;
  slot publisher :: <string>, init-keyword: publisher:;
  slot isbn :: <string>, init-keyword: isbn:;
  slot author :: <string>, init-keyword: author:;
end class;

begin
  let booker =
    method (record :: <record>) => (book :: <book>)
      let (title, publisher, isbn, last_name, first_name) =
        apply(values, record);

      make(<book>, title: title, publisher: publisher, 
           isbn: isbn, author: concatenate(last_name, ", ",
           first_name));
    end method;
let query = make(<sql-statement>,
                 statement: "select title, publisher, isbn,
                               last_name, first_name
                             from book, author, book_author
                             where book.isbn = book_author.isbn
                               and book_author.author_id = 
                                     author.author_id
                             order by author.last_name,
                                      author.first_name");
execute(query, liaison: booker
        result-set-policy: 
          make(<forward-only-result-set-policy>));
end;