Isql enhancements in Firebird v2. --------------------------------- Author: Claudio Valderrama C. 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.