osql (utilidad)

La utilidad osql permite especificar archivos de scripts, procedimientos de sistema e instrucciones Transact-SQL. Esta herramienta utiliza ODBC para comunicarse con el servidor.

Importante
Esta característica se quitará en una versión futura de SQL Server. Evite utilizar esta característica en los nuevos trabajos de programación y planee modificar las aplicaciones que actualmente la utilizan. En su lugar, use sqlcmd. Para obtener más información, vea sqlcmd (utilidad).

Sintaxis

osql
[-?] |
[-L] |
[
  {
     {-Ulogin_id [-Ppassword]} | –E }
     [-Sserver_name[\instance_name]] [-Hwksta_name] [-ddb_name]
     [-ltime_out] [-ttime_out] [-hheaders]
     [-scol_separator] [-wcolumn_width] [-apacket_size]
     [-e] [-I] [-D data_source_name]
     [-ccmd_end] [-q "query"] [-Q"query"]
     [-n] [-merror_level] [-r {0 | 1}]
     [-iinput_file] [-ooutput_file] [-p]
     [-b] [-u] [-R] [-O]
]

Argumentos

• -?
  Muestra el resumen de la sintaxis de los modificadores de osql.

• -L
  Enumera los servidores configurados localmente y los nombres de los servidores que difunden en la red.

  [!NOTA]

  Debido a la naturaleza de la difusión en las redes, osql puede no recibir una respuesta a tiempo de todos los servidores. Por lo tanto, la lista de servidores devuelta puede variar para cada invocación de esta opción.

• -U login_id
  Es el identificador de inicio de sesión del usuario. Los identificadores de inicio de sesión distinguen entre mayúsculas y minúsculas.

• -P password
  Es una contraseña especificada por el usuario. Si no se utiliza la opción -P, osql solicitará una contraseña. Si se utiliza la opción -P al final del símbolo del sistema sin una contraseña, osql utilizará la contraseña predeterminada (NULL).

  Nota de seguridad
  No utilice una contraseña en blanco. Utilice una contraseña segura. Para obtener más información, vea Contraseñas seguras.

  En las contraseñas se distingue entre mayúsculas y minúsculas.

  La variable de entorno OSQLPASSWORD le permite establecer una contraseña predeterminada para la sesión actual. Por lo tanto, no tiene que codificar una contraseña en archivos por lotes.

  Si no establece la contraseña con la opción -P, osql comprueba primero la variable OSQLPASSWORD. Si no hay ningún valor establecido, osql utiliza la contraseña predeterminada, NULL. En el ejemplo siguiente se especifica la variable OSQLPASSWORD en el símbolo del sistema y, a continuación, se tiene acceso a la utilidad osql:

  C:\>SET OSQLPASSWORD=abracadabra
  C:\>osql 
  

  Nota de seguridad
  Para enmascarar la contraseña, no especifique la opción -P junto con la opción -U. En su lugar, después de especificar osql con la opción -U y otros modificadores (no especifique -P), presione ENTRAR y osql le solicitará una contraseña. Este método garantiza que la contraseña se enmascare al especificarla.

• -E
  Utiliza una conexión de confianza en lugar de solicitar una contraseña.

• -S server_name[ **\instance_name]
  Especifica la instancia de SQL Server a la que hay que conectarse. Especifique server_name para conectarse a la instancia predeterminada del SQL Server en dicho servidor. Especifique server_name\**instance_name para conectarse a una instancia con nombre de SQL Server en dicho servidor. Si no se especifica ningún servidor, osql se conecta a la instancia predeterminada de SQL Server en el equipo local. Esta opción es necesaria cuando se ejecuta osql desde un equipo remoto conectado a la red.

• -H wksta_name
  Es el nombre de una estación de trabajo. El nombre de la estación de trabajo se almacena en sysprocesses.hostname y se muestra mediante sp_who. Si no se especifica esta opción, se supone el nombre actual del equipo.

• -d db_name
  Emite una instrucción USE db_name al iniciar osql.

• -l time_out
  Especifica el número de segundos que tienen que transcurrir antes de que un inicio de sesión de osql agote el tiempo de espera. El tiempo de espera predeterminado para el inicio de sesión de osql es de ocho segundos.

• -t time_out
  Especifica el número de segundos que tienen que transcurrir antes de que un comando exceda el tiempo de espera. Si no se especifica ningún valor para time_out, los comandos no tienen tiempo de espera.

• -h headers
  Especifica el número de filas que se van a imprimir entre los encabezados de las columnas. La opción predeterminada es imprimir los encabezados una vez para cada conjunto de resultados de la consulta. Utilice -1 para especificar que no desea imprimir los encabezados. Si utiliza -1, no debe dejar espacio entre el parámetro y el valor (-h-1, no -h -1).

• -s col_separator
  Especifica el carácter separador de columnas que, de forma predeterminada, es un espacio en blanco. Para utilizar caracteres con un significado especial para el sistema operativo (por ejemplo, | ; & < >), escríbalos entre comillas dobles (").

• -w column_width
  Permite al usuario ajustar el ancho de la pantalla para la salida. El valor predeterminado es 80 caracteres. Cuando una línea de salida ha alcanzado el ancho máximo de pantalla, se divide en varias líneas.

• -a packet_size
  Permite solicitar un paquete de diferente tamaño. Los valores válidos de packet_size son de 512 a 65535. El valor predeterminado es osql es el servidor predeterminado. Si se aumenta el tamaño del paquete, se puede mejorar el rendimiento durante la ejecución de scripts grandes en las que hay muchas instrucciones SQL entre comandos GO. Las pruebas de Microsoft indican que 8192 suele ser la configuración más rápida para operaciones de copia masiva. Se puede solicitar un tamaño mayor para los paquetes, pero osql adopta el valor predeterminado para el servidor si no puede cumplirse la solicitud.

• -e
  Muestra lo escrito.

• -I
  Activa la opción de conexión QUOTED_IDENTIFIER.

• -D data_source_name
  Conecta a un origen de datos ODBC definido mediante el controlador ODBC de SQL Server. La conexión osql utiliza las opciones especificadas en el origen de datos.

  [!NOTA]

  Esta opción no funciona con los orígenes de datos definidos para otros controladores.

• -c cmd_end
  Especifica el terminador del comando. De forma predeterminada, los comandos se terminan y se envían a SQL Server si se escribe GO en una línea aparte. Cuando restablezca el terminador del comando, no utilice palabras reservadas de Transact-SQL ni caracteres que tengan un significado especial para el sistema operativo, vayan o no precedidos por una barra diagonal inversa.

• -q " query "
  Ejecuta una consulta cuando se inicia osql, pero no sale de osql cuando se completa la consulta. (La instrucción de consulta no debe incluir GO.) Si emite una consulta desde un archivo por lotes, utilice %variables o %variables% de entorno. Por ejemplo:

  SET table=sys.objects
  osql -E -q "select name, object_id from %table%"
  

  Utilice comillas dobles para la consulta y comillas simples en los elementos que incruste en la consulta.

• -Q" query "
  Ejecuta una consulta y sale inmediatamente de osql. Utilice comillas dobles para la consulta y comillas simples en los elementos que incruste en la consulta.

• -n
  Quita la numeración y el símbolo del sistema (>) de las líneas de entrada.

• -m error_level
  Personaliza la presentación de los mensajes de error. Se muestra el nivel de error, estado y número de mensaje en errores con el nivel de gravedad especificado o superior. No se mostrarán errores que tengan un nivel de gravedad inferior al nivel especificado. Utilice -1 para especificar que se devuelvan todos los encabezados con los mensajes, incluso con los mensajes informativos. Si usa -1, no debe dejar espacio entre el parámetro y los valores (-m-1, no -m -1).

• -r { 0| 1}
  Redirige la salida del mensaje a la pantalla (stderr). Si no especifica ningún parámetro, o si especifica 0, solo se redirigirán los mensajes con nivel de gravedad 11 o superior. Si especifica 1, toda salida de mensaje (incluida "print") se redirigirá.

• -i input_file
  Identifica el archivo que contiene un lote de instrucciones SQL o procedimientos almacenados. Se puede utilizar el operador de comparación menor que (<) en lugar de -i.

• -o output_file
  Identifica el archivo que recibe la salida de osql. Se puede utilizar el operador de comparación mayor que (>) en lugar de -o.

  Si input_file no está en formato Unicode y no se especifica -u, output_file se almacena en formato OEM. Si input_file está en formato Unicode o se especifica -u, output_file se almacena en formato Unicode.

• -p
  Imprime las estadísticas de rendimiento.

• -b
  Especifica que osql se cierre y devuelva un valor de DOS ERRORLEVEL cuando se produce un error. El valor que se devuelve a la variable DOS ERRORLEVEL es 1 cuando el mensaje de error de SQL Server tiene una gravedad superior a 11; de lo contrario, el valor devuelto es 0. Los archivos por lotes de Microsoft MS-DOS pueden probar el valor de DOS ERRORLEVEL y tratar el error apropiadamente.

• -u
  Especifica que output_file se almacena en formato Unicode, independientemente del formato del input_file.

• -R
  Especifica que el controlador ODBC de SQL Server debe utilizar la configuración del cliente cuando realice conversiones de datos de moneda, fecha y hora a datos de carácter.

• -O
  Especifica que se desactiven algunas características de osql para emular el comportamiento de versiones anteriores de isql. Estas características están desactivadas:

  • Procesamiento por lotes de final de archivo (EOF)

  • Escala automática de ancho de la consola

  • Mensajes detallados

  También establece -1 como valor predeterminado de ERRORLEVEL de DOS.

[!NOTA]

Las opciones -n, -O y -D han dejado de admitirse en osql.

Comentarios

La utilidad osql se inicia directamente desde el sistema operativo con las opciones en mayúsculas o en minúsculas, tal como se muestran aquí. Después de iniciar osql, acepta instrucciones SQL y las envía a SQL Server de forma interactiva. Se da formato a los resultados y se muestran en la pantalla (stdout). Utilice QUIT o EXIT para salir de osql.

Si no especifica un nombre de usuario cuando inicia osql, SQL Server comprueba las variables de entorno y las utiliza, por ejemplo, osqluser=(user) u osqlserver=(server). Si no se establecen variables de entorno, se utilizará el nombre de usuario de la estación de trabajo. Si no especifica un servidor, se utilizará el nombre de la estación de trabajo.

Si no se utilizan las opciones -U ni -P, SQL Server intenta conectarse utilizando el modo de autenticación de Microsoft Windows. La autenticación se basa en la cuenta de Microsoft Windows del usuario que ejecuta osql.

La utilidad osql utiliza la API de ODBC. La utilidad utiliza la configuración predeterminada del controlador ODBC de SQL Server para las opciones de conexión ISO de SQL Server. Para obtener más información, vea Efectos de las opciones de ANSI.

[!NOTA]

La utilidad osql no admite los tipos de datos definidos por el usuario CLR. Para procesar estos tipos de datos, debe usar la utilidad sqlcmd. Para obtener más información, vea sqlcmd (utilidad).

Comandos OSQL

Además de las instrucciones de Transact-SQL de osql, los siguientes comandos también están disponibles.

Comando	Descripción
GO	Ejecuta todas las instrucciones escritas después del último GO.
RESET	Borra cualquier instrucción que haya escrito.
QUIT o EXIT( )	Sale de osql.
CTRL+C	Finaliza una consulta sin salir de osql.

[!NOTA]

Los comandos !! y ED ya no se admiten en osql.

Los terminadores del comando GO (predeterminado), RESET EXIT, QUIT y CTRL+C solo se reconocen si aparecen al principio de una línea, inmediatamente después de símbolo del sistema de osql.

GO marca tanto el final de un lote como la ejecución de cualquier instrucción de Transact-SQL almacenada en caché. Cuando presione ENTRAR al final de cada línea de entrada, osql colocará en caché las instrucciones de esa línea. Al presionar ENTRAR después de escribir GO, todas las instrucciones almacenadas en la caché se enviarán como un lote a SQL Server.

La utilidad osql actual funciona como si existiera una instrucción GO al final de cada script que se ejecuta, por lo que se ejecutarán todas las instrucciones del script.

Finalice un comando; para ello, escriba una línea que comience con un terminador de comandos. Puede poner un entero después del terminador de comandos para especificar cuántas veces se debe ejecutar el comando. Por ejemplo, para ejecutar este comando 100 veces, escriba:

SELECT x = 1
GO 100

Los resultados se imprimen una vez al final de la ejecución. osql no acepta más de 1.000 caracteres por línea. Las instrucciones grandes se deben distribuir en varias líneas.

Pueden utilizarse las funciones de recuperación de Windows NT para recuperar y modificar las instrucciones osql. El búfer de consulta existente se puede borrar si escribe RESET.

Cuando se ejecutan procedimientos almacenados, osql imprime una línea en blanco entre cada conjunto de resultados de un lote. Además, el mensaje "0 filas afectadas" no aparece cuando no se aplica a la instrucción ejecutada.

Utilizar osql de forma interactiva

Para utilizar osql de forma interactiva, escriba el comando osql (y cualesquiera de las opciones) junto al símbolo del sistema.

Puede leer un archivo que contenga una consulta (como Sores.qry) para ejecutarse en osql si escribe un comando como este:

osql -E -i stores.qry

Puede leer un archivo que contenga una consulta (como Titles.qry) y dirigir el resultado a otro archivo si escribe un comando similar a este:

osql -E -i titles.qry -o titles.res

Nota de seguridad
Siempre que sea posible, utilice la opción -E (conexión de confianza).

Cuando utilice osql de forma interactiva, podrá leer un archivo del sistema operativo en el búfer de comandos con :r file_name. De esta manera, se enviará el script SQL de file_name directamente al servidor como un lote único.

[!NOTA]

Cuando se utiliza osql, SQL Server trata el separador de lotes GO, si aparece en el archivo de script de SQL, como un error de sintaxis.

Insertar comentarios

Puede incluir comentarios en una instrucción Transact-SQL que vaya a enviarse a SQL Server con osql. Se permiten dos estilos de comentario: -- y /*...*/.

Utilizar EXIT para devolver resultados en osql

Puede utilizar el resultado de una instrucción SELECT como valor devuelto de osql. Si es numérica, la primera columna de la última fila del resultado se convierte en un entero de 4 bytes (long). MS-DOS pasa el byte bajo al proceso primario o al nivel de errores del sistema operativo. Windows pasa el entero de 4 bytes completo. La sintaxis es:

EXIT ( < query > )

Por ejemplo:

EXIT(SELECT @@ROWCOUNT)

También puede incluir el parámetro EXIT como parte de un archivo por lotes. Por ejemplo:

osql -E -Q "EXIT(SELECT COUNT(*) FROM '%1')"

La utilidad osql pasa al servidor todo lo que haya entre paréntesis ( ), exactamente como se haya escrito. Si un procedimiento almacenado del sistema selecciona un conjunto y devuelve un valor, solo se devuelve la selección. La instrucción EXIT**(** ) sin nada entre paréntesis ejecuta todo lo que le precede en el lote y luego sale sin ningún valor devuelto.

Hay cuatro formatos de EXIT:

• EXIT

[!NOTA]

No ejecuta el lote; sale de forma inmediata y no devuelve ningún valor.

• EXIT**(** )

[!NOTA]

Ejecuta el lote y, a continuación, sale sin devolver ningún valor.

• EXIT**(query)**

[!NOTA]

Ejecuta el lote, incluida la consulta, y, a continuación, sale tras devolver el resultado de la consulta.

• RAISERROR con un estado de 127

[!NOTA]

Si utiliza RAISERROR en un script osql y se genera el estado 127, osql terminará y devolverá un identificador de mensaje al cliente. Por ejemplo:

RAISERROR(50001, 10, 127)

Este error provocará la finalización del script osql y se devolverá al cliente un mensaje con el identificador 50001.

SQL Server reserva los valores devueltos -1 a -99; osql define los valores siguientes:

• -100

  Error encontrado antes de seleccionar el valor devuelto.

• -101

  No se encontró ninguna fila al seleccionar el valor devuelto.

• -102

  Error de conversión al seleccionar el valor devuelto.

Mostrar tipos de datos money y smallmoney

osql muestra los tipos de datos money y smallmoney con dos decimales, aunque SQL Server almacene internamente el valor con cuatro decimales. Observe el ejemplo:

SELECT CAST(CAST(10.3496 AS money) AS decimal(6, 4))
GO

Esta instrucción da como resultado 10.3496, que indica que el valor se almacena con todos los decimales intactos.

Vea también

Referencia

/*...*/ (Comentario) (MDX)

-- (Comentario) (MDX)

CAST y CONVERT (Transact-SQL)

RAISERROR (Transact-SQL)