osql (utilidad)

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

Importante:
Esta característica se eliminará en una próxima versión de Microsoft SQL Server. Evite utilizar esta característica en nuevos trabajos de desarrollo y tenga previsto modificar las aplicaciones que actualmente la utilizan. En su lugar, utilice 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, sqlcmd 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.

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

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

  Nota de seguridad:
  No utilice una contraseña en blanco. Utilice una contraseña de alta seguridad. 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 junto 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 enmascarará cuando se especifique.

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

• -S server_name[ **\instance_name]
  Especifica la instancia de Microsoft SQL Server a la que hay que conectarse. Especifique server_name para conectarse a la instancia predeterminada de SQL Server en ese servidor. Especifique server_name\**instance_name para conectar con una instancia con nombre de SQL Server en ese 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 cuando se inicia osql.

• -ltime_out
  Especifica el número de segundos que tienen que transcurrir antes de que un inicio de sesión 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.

• -apacket_size
  Permite pedir un paquete de diferente tamaño. Los valores válidos para packet_size van de 512 a 65.535. El valor predeterminado para osql es el valor predeterminado para el servidor. Si se aumenta el tamaño del paquete, se puede mejorar el rendimiento durante la ejecución de secuencias de comandos 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 pedir un tamaño mayor para los paquetes, pero osql adopta el valor predeterminado para el servidor si no puede cumplirse la petición.

• -e
  Muestra lo escrito.

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

• -Ddata_source_name
  Conecta a un origen de datos ODBC que se define mediante el controlador ODBC de Microsoft 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 finaliza 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 utiliza -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, sólo 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 devuelto en la variable DOS ERRORLEVEL es 1 cuando el mensaje de error de SQL Server tiene un nivel de gravedad 11 o superior; de lo contrario, se devuelve el valor 0. Los archivos de proceso por lotes de Microsoft MS-DOS pueden comprobar el valor de DOS ERRORLEVEL y tratar el error adecuadamente.

• -u
  Especifica que output_file se almacena en formato Unicode, independientemente del formato de 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 funciones de osql para emular el comportamiento de versiones anteriores de isql. Estas características están desactivadas:

  • Proceso 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.

Notas

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 su inicio, 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) o 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 conectar 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 SQL-92 de SQL Server. Para obtener más información, vea Efectos de las opciones de SQL-92.

[!NOTA] La utilidad osql no admite los tipos de datos definidos por el usuario CLR. Para procesar esos tipos de datos, es preciso utilizar 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, ED, !!, EXIT, QUIT y CTRL+C sólo 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 herramienta osql actual funciona como si existiera una instrucción GO al final de cada secuencia de comandos que se ejecuta, por lo que se ejecutarán todas las instrucciones de la secuencia.

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 STORES.QRY) para su ejecución en osql si escribe un comando como éste:

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:
Cuando 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 :rfile_name. Esto envía la secuencia de comandos 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 secuencia de comandos 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 /*...*/.

Para obtener más información, vea Usar comentarios.

Utilizar EXITpara devolver resultados en osql

Puede utilizar el resultado de una instrucción SELECT como valor devuelto de osql. La primera columna de la primera 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, sólo 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 una secuencia de comandos osql y se genera un estado 127, osql terminará y devolverá un Id. de mensaje al cliente. Por ejemplo:

RAISERROR(50001, 10, 127)

Este error provocará la finalización de la secuencia de comandos osql y se devolverá al cliente un mensaje con el Id. 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 guarde 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 guarda con todos los decimales intactos.

Vea también

Otros recursos

/*...*/ (Comentario) (MDX)
-- (Comentario) (MDX)
CAST y CONVERT (Transact-SQL)
Proteger Notification Services
RAISERROR (Transact-SQL)

Ayuda e información

Obtener ayuda sobre SQL Server 2005