Command-line switches

<< Invoking isql | Firebird Interactive SQL Utility | Starting an isql session >>

Command-line switches

Command line switches are arguments that begin with a minus/hyphen (-) character. The following is an example of what happens when you attempt to start isql with an invalid switch - it displayes the list of valid switches with a brief explanation of each. 

 tux> $ isql --help 

 Unknown switch: -help
 usage:    isql [options] [<database>]
         -a(ll)                  extract metadata incl. legacy non-SQL tables
         -b(ail)                 bail on errors (set bail on)
         -c(ache) <num>          number of cache buffers
         -ch(arset) <charset>    connection charset (set names)
         -d(atabase) <database>  database name to put in script creation
         -f(etch_password)       fetch password from file
         -e(cho)                 echo commands (set echo on)
         -ex(tract)              extract metadata
         -i(nput) <file>         input file (set input)
         -m(erge)                merge standard error
         -m2                     merge diagnostic
         -n(oautocommit)         no autocommit DDL (set autoddl off)
         -nod(btriggers)         do not run database triggers
         -now(arnings)           do not show warnings
         -o(utput) <file>        output file (set output)
         -pag(elength) <size>    page length
         -p(assword) <password>  connection password
         -q(uiet)                do not show the message "Use CONNECT..."
         -r(ole) <role>          role name
         -r2 <role>              role (uses quoted identifier)
         -s(qldialect) <dialect> SQL dialect (set sql dialect)
         -t(erminator) <term>    command terminator (set term)
         -u(ser) <user>          user name
         -x                      extract metadata
         -z                      show program and server version

Not all of these switches appear in every release of Firebird. Some will be seen in more more recent releases. Many of the switches have an equivalent SET command, and these will be discussed below.

  • Using -b(ail):

The command line switch -b(ail) instructs the isql utility to bail on error, but only when used in a non-interactive mode. The switch returns an error code to the operating system.

This switch was added to prevent isql from executing scripts after an error has been detected. No further statements will be executed and isql will return an error code to the OS.

Users still need to use the -e(cho) switch to echo commands to an output file, to isolate the exact statement that caused the error.

When the server provides line and column information, users can see the exact line of the DML in the script that caused the problem. When the server only indicates failure, users can view the first line of the statement that caused the failure, in relation to the entire script.

This feature is also supported in nested scripts. For example, Script A includes Script B and Script B causes a failure, the line number is related to Script B. When Script B is read completely, isql continues counting the lines related to Script A, since each file gets a separate line counter. Script A includes Script B when Script A uses the INPUT command to load Script B.

Lines are counted according to what the underlying IO layer considers separate lines. For ports using EDITLINE, a line is what readline() provides in a single call. The line length limit of 32767 bytes remains uncharged.

  • Using -ex(tract):

The command line switch -ex(tract) can be used to extract meta data from the database. It can be used in conjunction with the -o(utput) switch to extract the information to a specified output file.

The resultant information can be used to view all the changes made to the database since its creation. Before making any more changes, create a new database with identical schema definitions or new ones, or create a new database source file.

  • Using -m2 and -m(erge):

The command line switch m2, has been added in Firebird 2.0 and can be used to send the statistics and plans to the same output file that receives the input from the -o(utput) switch. In earlier versions of Firebird (before version 2.0), when a user specified that the output should be sent to a file, two options existed : the command line switch -o(utput) with a file name to store the output, or the command OUTput with a file name to store the output. Both these options could be employed either in a batch session or in the interactive isql shell. In both cases, simply passing the command OUTput would return the output to the console. While the console displayed error messages, these were not sent to the output file.

The -m(erge) command line switch, can be used to incorporate the error messages into the output files.

The -m2 command line switch ensures that the stats and plan information derived from the SET STATS, SET PLAN and SET PLANONLY commands are also sent to the output file and not just returned to the console.

Note: Neither -m(erge) nor -m2 has an interactive counterpart through a SET command. They are for use only as command-line isql options.

  • Using -r2 and -r(ole):

This switch can be used to specify a case-sensitive role name. The default switch for this is -r(ole). Roles provided in the command line are uppercased With -r2, and passed to the engine exactly as typed in the command line.

  • Using -o(utput):

The OUTPUT switch allows users to store records of commands to a script file. The TMP setting on a client can be used to control where these script files will be stored, if an absolute file path is not specified.

See also:
Firebird and InterBase® command-line utilities: isql
Firebird 2.1.3 Release Notes: Command-line utilities
Firebird 2.0.4 Release Notes: Command-line utilities

back to top of page
<< Invoking isql | Firebird Interactive SQL Utility | Starting an isql session >>