public Class SqlFile

The file src/org/hsqldb/sample/SqlFileEmbedder.java in the HSQLDB distribution provides an example for using SqlFile to execute SQL files directly from your own Java classes.

The complexities of passing userVars and macros maps are to facilitate strong scoping (among blocks and nested scripts).

Some implementation comments and variable names use keywords based on the following definitions.

• COMMAND = Statement || SpecialCommand || BufferCommand
• Statement = SQL statement like "SQL Statement;"
• SpecialCommand = Special Command like "\x arg..."
• BufferCommand = Editing/buffer command like ":s/this/that/"

When entering SQL statements, you are always "appending" to the "immediate" command (not the "buffer", which is a different thing). All you can do to the immediate command is append new lines to it, execute it, or save it to buffer. When you are entering a buffer edit command like ":s/this/that/", your immediate command is the buffer-edit-command. The buffer is the command string that you are editing. The buffer usually contains either an exact copy of the last command executed or sent to buffer by entering a blank line, but BUFFER commands can change the contents of the buffer.

In general, the special commands mirror those of Postgresql's psql, but SqlFile handles command editing very differently than Postgresql does, in part because of Java's lack of support for raw tty I/O. The \p special command, in particular, is very different from psql's.

Buffer commands are unique to SQLFile. The ":" commands allow you to edit the buffer and to execute the buffer.

\d commands are very poorly supported for Mysql because (a) Mysql lacks most of the most basic JDBC support elements, and the most basic role and schema features, and (b) to access the Mysql data dictionary, one must change the database instance (to do that would require work to restore the original state and could have disastrous effects upon transactions).

The process*() methods, other than processBuffHist() ALWAYS execute on "buffer", and expect it to contain the method specific prefix (if any).

The input/output Reader/Stream are generally managed by the caller. An exception is that the input reader may be closed automatically or on demand by the user, since in some cases this class builds the Reader. There is no corresponding functionality for output since the user always has control over that object (which may be null or System.out).