isql Utility
The isql utility allows you to enter Transact-SQL statements, system procedures, and script files; and uses DB-Library to communicate with Microsoft® SQL Server™ 2000.
Syntax
isql
[-?] |
[-L] |
[
{
{-U login_id [-P password]}
| –E
}
[-S server_name] [-H wksta_name] [-d db_name]
[-l time_out] [-t time_out] [-h headers]
[-s col_separator] [-w column_width] [-a packet_size]
[-e] [-x max_text_size]
[-c cmd_end] [-q "query"] [-Q "query"]
[-n] [-m error_level] [-r {0 | 1}]
[-i input_file] [-o output_file] [-p]
[-b] [-O]
]
Arguments
-?
Displays the syntax summary of isql switches.
-L
Lists the locally configured servers and the names of the servers broadcasting on the network.
-U login_id
Is the user login ID. Login IDs are case-sensitive.
-P password
Is a user-specified password. If the -P option is not used, isql prompts for a password. If the -P option is used at the end of the command prompt without any password, isql uses the default password (NULL). Passwords are case-sensitive.
The ISQLPASSWORD environment variable allows you to set a default password for the current session. Therefore, you do not have to hard code a password into batch files.
If you do not specify a password with the -P option, isql first checks for the ISQLPASSWORD variable. If no value is set, isql uses the default password, NULL. The following example sets the ISQLPASSWORD variable at the command prompt and then accesses the isql utility:
C:\>SET ISQLPASSWORD=abracadabra
C:\>isql
-E
Uses a trusted connection instead of requesting a password.
-S server_name
Specifies the default instance of SQL Server to connect to. isql does not support connecting to a named instance of SQL Server 2000. If no server is specified, isql connects to the default instance of SQL Server on the local computer. This option is required if you are executing isql from a remote computer.
-H wksta_name
Is a workstation name. The workstation name is stored in sysprocesses.hostname and is displayed by sp_who. If not specified, the current computer name is assumed.
-d db_name
Issues a USE db_name statement when isql is started.
-l time_out
Specifies the number of seconds before an isql login times out. If no time_out value is specified, a command runs indefinitely. The default time-out for login to isql is eight seconds.
-t time_out
Specifies the number of seconds before a command times out. If no time_out value is specified, a command runs indefinitely; the default time-out for logging in to isql is eight seconds.
-h headers
Specifies the number of rows to print between column headings. The default is to print headings one time for each set of query results. Use -1 to specify that no headers will be printed. If using -1, there must be no space between the parameter and the setting (-h-1, not -h -1).
-s col_separator
Specifies the column-separator character, which is a blank space by default. To use characters that have special meaning to the operating system (for example, | ; & < >), enclose the character in double quotation marks (").
-w column_width
Allows the user to set the screen width for output. The default is 80 characters. When an output line has reached its maximum screen width, it is broken into multiple lines.
-a packet_size
Allows you to request a different-sized packet. The valid values for packet_size are 512 through 65535. The default value for the Microsoft Windows NT® version of isql is 8192; otherwise, the default value is 512 for Microsoft MS-DOS®, although larger sizes can be requested with that version as well. Increased packet size can enhance performance on larger script execution where the amount of SQL statements between GO commands is substantial. Microsoft testing indicates that 8192 is typically the fastest setting for bulk copy operations. A larger packet size can be requested, but isql defaults to 512 if the request cannot be granted.
-e
Echoes input.
-x max_text_size
Specifies, in bytes, the maximum length of text data to return. Text values longer than max_text_size are truncated. If max_text_size is not specified, text data is truncated at 4096 bytes.
-c cmd_end
Specifies the command terminator. By default, commands are terminated and sent to SQL Server 2000 by entering GO on a line by itself. When you reset the command terminator, do not use Transact-SQL reserved words or characters that have special meaning to the operating system, whether preceded by a backslash or not.
-q "query"
Executes a query when isql starts, but does not exit isql when the query completes. (Note that the query statement should not include GO). If you issue a query from a batch file, you can use %variables. Environment %variables% also work. For example:
SET table = sysobjects
isql /q "Select * from %table%"
Use double quotation marks around the query and single quotation marks around anything embedded in the query.
-Q "query"
Executes a query and immediately exits isql when the query completes. Use double quotation marks around the query and single quotation marks around anything embedded in the query.
-n
Removes numbering and the prompt symbol (>) from input lines.
-m error_level
Customizes the display of error messages. The message number, state, and error level are displayed for errors of the specified severity level or higher. Nothing is displayed for errors of severity levels lower than the specified level. Use -1 to specify that all headers are returned with messages, even informational messages. If -1 is used, there must be no space between the parameter and the setting (-m-1, not -m -1).
-r {0 | 1}
Redirects message output to the screen (stderr). If you do not specify a parameter, or if you specify 0, only error messages with severity 17 or higher are redirected. If you specify 1, all message output (including "print") is redirected.
-i input_file
Identifies the file that contains a batch of SQL statements or stored procedures. The less than (<) comparison operator can be used in place of -i.
-o output_file
Identifies the file that receives output from isql. The greater than (>) comparison operator can be used in place of -o.
-p
Prints performance statistics.
-b
Specifies that isql exits and returns a DOS ERRORLEVEL value when an error occurs. The value returned to the DOS ERRORLEVEL variable is 1 when the SQL Server error message has a severity of 10 or greater; otherwise, the value returned is 0. MS-DOS batch files can test the value of DOS ERRORLEVEL and handle the error appropriately.
-O
Specifies that isql reverts to the behavior of earlier versions. These features are deactivated:
- EOF batch processing
- Automatic console width scaling
- Wide messages
This option also sets the default DOS ERRORLEVEL value to -1.
Remarks
All DB-Library applications, such as isql, work as SQL Server 6.5–level clients when connected to SQL Server 2000. They do not support some SQL Server 2000 features. The osql utility is based on ODBC and does support all SQL Server 2000 features. Use osql to run scripts that isql cannot run. For more information about the restrictions on SQL Server 6.5–level clients, see Connecting Early Version Clients to SQL Server 2000 in SQL Server Books Online.
The SQL Query Analyzer default is to save SQL scripts as Unicode files. The isql utility does not support Unicode input files. Attempting to specify one of these files in the -i switch results in a 170 error:
Incorrect syntax near ' '.
Use the osql utility to run these Unicode files. An alternative is to specify ANSI instead of Unicode in the File format list of the SQL Query Analyzer File/Save As dialog box.
Like most DB-Library applications, the isql utility does not set any connection options by default. Users must issue SET statements interactively or in their scripts if they want to use specific connection option settings.
The isql utility is started directly from the operating system with the case-sensitive options listed here. After starting, isql accepts Transact-SQL statements and sends them to SQL Server 2000 interactively. The results are formatted and printed on the standard output device (the screen). Use QUIT or EXIT to exit from isql.
If you do not specify a user name when you start isql, SQL Server 2000 checks for the environment variables and uses those, for example, isqluser=(user) or isqlserver=(server). If no environment variables are set, the workstation user name is used. If you do not specify a server, the name of the workstation is used.
If neither the -U or -P options are used, SQL Server 2000 attempts to connect using Windows Authentication Mode. Authentication is based on the Windows NT account of the user running isql.
In addition to using Transact-SQL statements within isql, the commands shown in this table are also available.
| Command | Description |
|---|---|
| GO | Executes all statements entered after the last GO. |
| RESET | Clears any statements you have entered. |
| ED | Calls the editor. |
| !! command | Executes an operating-system command. |
| QUIT or EXIT( ) | Exits from isql. |
| CTRL+C | Ends a query without exiting from isql. |
The command terminators GO (by default), RESET, ED, !!, EXIT, QUIT, and CTRL+C are recognized only if they appear at the beginning of a line, immediately following the isql prompt. Anything entered on the same line after these keywords is disregarded by isql.
GO signals both the end of a batch and the execution of any cached Transact-SQL statements. When you press ENTER at the end of each input line, isql caches the statements on that line. When you press ENTER after typing GO, all of the currently cached statements are sent as a batch to SQL Server 2000.
The current isql utility works as if there is an implied GO at the end of any script executed, therefore all statements in the script execute. Some earlier versions of isql do not send any statements to the server unless there is at least one GO in an input script. Any statements after the last GO are not executed.
End a command by typing a line beginning with a command terminator. You can follow the command terminator with an integer to specify how many times the command should be run. For example, to execute this command 100 times, type:
SELECT x = 1
GO 100
The results are printed once, at the end of execution. With isql, there is a limit of 1000 characters per line. Large statements should be spread across multiple lines.
The user can call an editor on the current query buffer by typing ED as the first word on a line. The editor is defined in the EDITOR environment variable. The default editor is "edit" for MS-DOS and Windows NT. You can specify a different editor by setting the EDITOR environment variable. For example, to make the default editor Notepad, enter at the operating-system prompt:
SET EDITOR=notepad
For more information about where to find or how to run this utility, see Getting Started with Command Prompt Utilities.
Operating-System Commands
Operating-system commands can also be executed by starting a line with two exclamation points (!!) followed by the command. The command recall facilities of DOSKEY can be used to recall and modify previously entered isql statements on a computer running Windows NT. The existing query buffer can be cleared by typing RESET.
When running stored procedures, isql prints a blank line between each set of results in a batch. In addition, the "0 rows affected" message does not appear when it does not apply to the statement executed.
Using isql Interactively
To use isql interactively, type the isql command (and any of the options) at a command prompt.
You can read in a file containing a query (such as Stores.qry) for execution by isql by typing a command similar to this:
isql /U alma /P /i stores.qry
The file must include a command terminator(s).
You can read in a file containing a query (such as Titles.qry) and direct the results to another file by typing a command similar to this:
isql /U alma /P /i titles.qry /o titles.res
When using isql interactively, you can read an operating-system file into the command buffer with :r file_name. Do not include a command terminator in the file; enter the terminator interactively after you have finished editing.
Inserting Comments
You can include comments in a Transact-SQL statement submitted to SQL Server 2000 by isql. Two types of commenting styles are allowed: -- and /*...*/.
For more information, see Using Comments.
Using EXIT to Return Results in isql
You can use the result of a SELECT statement as the return value from isql. The first column of the first result row is converted to a 4-byte integer (long). MS-DOS passes the low byte to the parent process or operating-system error level. Windows NT passes the entire 4-byte integer. The syntax is:
EXIT(query)
For example:
EXIT(SELECT @@rowcount)
EXIT(SELECT 5)
You can also include the EXIT parameter as part of a batch file. For example:
isql /Q "EXIT(SELECT COUNT(*) FROM '%1')"
The isql utility passes everything between the parentheses ( ) to the server exactly as entered. The EXIT( ) statement can span lines. If a stored system procedure selects a set and returns a value, only the selection is returned. The EXIT( ) statement with nothing between the parentheses executes everything preceding it in the batch and then exits with no return value.
There are four EXIT formats:
- EXIT
Does not execute the batch; quits immediately and returns no value.
- EXIT( )
Executes the batch, and then quits and returns no value.
- EXIT(query)
Executes the batch, including the query, and then quits after returning the results of the query.
- RAISERROR with a state of 127.
If RAISERROR is used within an isql script and a state of 127 is raised, isql will quit and return the message ID back to the client. For example:
RAISERROR(50001, 10, 127)This error will cause the isql script to end and the message ID 50001 will be returned to the client.
The return values -1 through -99 are reserved by SQL Server; isql defines the following values:
- -100
Error encountered prior to selecting return value.
- -101
No rows found when selecting return value.
- -102
Conversion error when selecting return value.