firebird-mirror/doc/README.isql_enhancements.txt

Isql enhancements in Firebird v2.
---------------------------------

Author: Claudio Valderrama C. <cvalde at usa.net>

1) Command line switch -b to bail out on error when used in non-interactive mode.

When using scripts as input in the command line, it may be totally unappropriate
to let isql continue executing a batch of commands after an error has happened.
Therefore, the "-b[ail]" option was created. It will stop at the first error it
can detect. Most cases have been covered, but if you find some error that's not
recognized by isql, you should inform the project, as this is a feature in progress.
When isql stops, it means it will no longer execute any command in the input script
and will return an error code to the operating system. At this time there aren't
different error codes. A return non-zero return code should be interpreted as failure.
Depending on other options (like -o, -m and -m2) , isql will show the error message
on screen or will send it to a file.

Some features:

- Even if isql is executing nested scripts, it will cease all execution and will
return to the operating system when it detects an error. Nested scripts happen
when a script A is used as isql input but in turn A contains an INPUT command to
load script B an so on. Isql doesn't check for direct or indirect recursion, thus
if the programmer makes a mistake and script A loads itself or loads script B that
in turn loads script A again, isql will run until it exhaust memory or an error
is returned from the database, at whose point -bail if activated will stop all
activity.

- The line number of the failure is not yet known. It has been a private test feature
for some years but needs more work to be included in the official isql.

- DML errors will be caught when being prepared or executed, depending on the type
of error.

- DDL errors will be caught when being prepared or executed by default, since isql
uses AUTODDL ON by default. However, if AUTO DLL is OFF, the server only complains
when the script does an explicit COMMIT and this may involve several SQL statements.

- The feature can be enabled/disabled interactively or from a script by means of the
SET BAIL [ON | OFF]
command. As it's the case with other SET commands, simply using SET BAIL will toggle
the state between activated and deactivated. Using SET will display the state of
the switch among many others.

- Even if BAIL is activated, it doesn't mean it will change isql behavior. An
additional requirement should be met: the session should be non-interactive. A
non-interactive session happens when the user calls isql in batch mode, giving it
a script as input. Example:
isql -b -i my_fb.sql -o results.log -m -m2
However, if the user loads isql interactively and later executes a script with the
input command, this is considered an interactive session even though isql knows it's
executing a script. Example:
isql
Use CONNECT or CREATE DATABASE to specify a database
SQL> set bail;
SQL> input my_fb.sql;
SQL> ^Z
Whatever contents the script has, it will be executed completely even with errors
and despite the BAIL option was enabled.


2) SET HEADING ON/OFF option.

Some people consider useful the idea of doing a SELECT inside isql and have the
output sent to a file, for additional processing later, specially if the number
of columns make isql display unpractical. However, isql by default prints column
headers and in this scenario, they are a nuisance. Therefore, the feature (that was
previously the fixed default) can be enabled/disabled interactively or from a script
by means of the
SET HEADing [ON | OFF]
command. As it's the case with other SET commands, simply using SET HEAD will toggle
the state between activated and deactivated. Using SET will display the state of
the switch among many others.
Note: this switch cannot be deactivated with a command line parameter.


3) Command line switch -m2 to send output of statistics and plans to the same file
than the rest of the output.

When the user specifies that the output should be sent to a file, two possibilities
have existed for years: either the command line switch -o followed by a file name
is used or once inside isql, the command OUTput followed by a file name is used at
any time, be it an interactive or a batch session. To return the output to the
console, simply typing OUTput; is enough. So far so good, but error messages
don't go to that file. They are shown in the console. Then isql developed the -m
command line switch to melt the error messages with the normal output to whatever
place the output was being redirected. This left still another case: statistics
about operations (SET STATs command) and SQL plans as the server returns them
(SET PLAN and SET PLANONLY commands) are considered diagnostic messages and thus
were sent always to the console. What the -m2 command line switch does is to
ensure that such information about stats and plans goes to the same file the output
has been redirected to.
Note: neither -m nor -m2 have interactive counterparts through the SET command.
They only can be specified in the command line switches for isql.