# /research/software/scorpion/documentation/writehandler.htm

originally: http://www.oclc.org/research/software/scorpion/documentation/writehandler.htm

# Writing a record set handler

After you've designed the database, you can create a class to format the results. The class that you write must implement the ORG.oclc.scorpion.RecordSetHandler interface.

There is only one method in the ORG.oclc.scorpion.RecordSetHandler interface:

  `public String process(Vector dirs, Vector qv, IniFile ini, StringBuffer text);`

At runtime, an instance of your class is created and the `process()` method is invoked on it.

Parameter | Description
--- | ---
`Vector dirs` | A Vector of ORG.oclc.ber.DataDir objects. Each DataDir object is a record from the database. There are two ways to extract information from DataDir objects. You could write your formatter to work directly with the DataDir objects and navigate through each of them to extract the data you want to present. If you do this, you'll need to know how the DataDir objects work. This "primer" should get you started. See the source for more information. You could use `ORG.oclc.scorpion.RecordCollection.flattenDataDir()` in your formatter. This method will flatten a DataDir object and return a Hashtable. (See here for more info) If you choose to do this, you'll have to provide Scorpion with a mapping of field IDs to field names. The names given will then be used as keys in the Hashtable objects. The mapping is specified in the Scorpion initialization file, under a section named [ScorpionFieldMap]. See here for an example.
`Vector qv` | A Vector of String objects. Each String object is a term from the input document that matched in the database. Note: This functionality existed in an earlier incarnation of Scorpion, but has been removed from this one. In hopes of putting the functionality back in, the parameter has been left in the interface. When the `process()` method is invoked on your class, it will be passed a null value for this parameter.
`IniFile ini` | A ORG.oclc.util.IniFile object. You can use this object to access the contents of the Scorpion initialization file.
`StringBuffer text` | A StringBuffer object. It contains the normalized input document.

The String object returned from your formatter will be written to a temp file. The contents of that file will be used by the Perl script to create the page returned to the client. Your formatted output need only be an HTML fragment, as the Perl script creates the HEAD element and starts the BODY element. It also will supply the close tags for the BODY and HTML elements.

The following classes are included with the distribution:

ORG.oclc.scorpion.lcc.LCCReccordCollection
  Implements the RecordSetHandler interface and extends RecordCollection. In its `process()` method, it uses the `flattenDir()` method to turn the DataDir objects into Hashtable objects. Depending on the parameters passed to the application, it will filter the record set. Finally, to format the record set, it will create an instance of the class specified in the [ORG.oclc.scorpion.lcc.LCCRecordCollection] section of the Scorpion initialization file. The specified class must implement the ORG.oclc.scorpion.lcc.LCCRecordFormatter interface.
ORG.oclc.scorpion.lcc.LCCFormatter
  Implements the ORG.oclc.scorpion.lcc.LCCRecordFormatter interface. The string returned is an HTML fragment.
ORG.oclc.scorpion.lcc.LCCFormatter2
  Implements the ORG.oclc.scorpion.lcc.LCCRecordFormatter interface. The string returned is an HTML fragment.
ORG.oclc.scorpion.lcc.LCCXMLFormatter
  Implements the ORG.oclc.scorpion.lcc.LCCRecordFormatter interface. The string returned is XML.