osql (utilidad)

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

Nota importanteImportante

Esta característica se quitará en una versión futura de SQL Server. Evite usar esta característica en los nuevos trabajos de desarrollo y piense cómo modificar las aplicaciones que la usan actualmente. Use sqlcmd en su lugar. 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.

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

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

    Nota de seguridadNota de seguridad

    No use una contraseña en blanco. Use 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 usa 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 seguridadNota 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.

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

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

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

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

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

  • -hheaders
    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. Use -1 para especificar que no desea imprimir los encabezados. Si usa -1, no debe dejar espacio entre el parámetro y el valor (-h-1, no -h -1).

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

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

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

    Nota

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

  • -ccmd_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 use 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, use %variables o %variables% de entorno. Por ejemplo:

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

    Use 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. Use 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.

  • -merror_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. Use -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á.

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

  • -ooutput_file
    Identifica el archivo que recibe la salida de osql. Se puede usar 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 usar 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). Use 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 usa, 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 usa la API de ODBC. La utilidad usa 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 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 usar 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 seguridadNota de seguridad

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

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

Nota

Cuando se usa 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 /*...*/.

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

Utilizar EXIT para devolver resultados en osql

Puede usar 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, 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 usa 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.