Although the outcome is quite similar, let me describe how the
Query Dispatcher actually works to clear up any confusion.
When a package is loaded (at server startup time), its Tcl files
are loaded as well as its Query files (the .xql) files. The specific
naming of the query files (-oracle or -postgres) doesn't really
affect the Query Dispatcher: it's just loading up all query files as
spec'ed in the package's .info file.
Thus, when a query is loaded from a .xql file, it is checked (at
load-time! Not at execution time) against the current running DB
(Oracle or Postgres for now) for compatibility. If there is already a
compatible loaded query with that name, the queries are
compared for levels of compatibility: the more specific query is
kept, and the more generic query is discarded.
Thus, as soon as your OpenACS instance is up and running, it
has a cache of the most-compatible queries available for the
specific RDBMS on which it is running.
Then, when a call is made to execute a query, the Query
Dispatcher looks up the query name in the cache. If *no*
compatible query was loaded for that query name, then the
default SQL provided at the Tcl layer is used. HOWEVER, you
should expect that this behavior will eventually stop: we want to
remove all SQL from the Tcl code. Thus, even if the query is very
simple and SQL92 compliant, please move it out into a .xql file.
Now, even though the naming of the specific .xql file is currently
not used to determine DB compatibilty (instead, we use the
compatibility information in the XML of the query file), you should
still respect the convention of putting Oracle queries in -oracle,
Postgres in -postgres, and SQL92 in the generic file. At some
future date, we may begin to infer meaning from the filename
(this is mentioned in the spec!). So, please respect the
convention.
Finally, Gilbert, your description of how you would go about
porting the survey package is correct. These are good
questions, keep them coming to help make everyone's porting
job easier!
