Utilitário osql

O utilitário osql permite inserir instruções Transact-SQL, procedimentos de sistema e arquivos de script. Esse utilitário usa o ODBC para comunicar-se com o servidor.

Importante
Esse recurso será removido em uma versão futura do SQL Server. Evite usar esse recurso em novo trabalho de desenvolvimento e planeje modificar os aplicativos que utilizam o recurso atualmente. Em vez disso, use sqlcmd. Para obter mais informações, consulte Utilitário sqlcmd.

Sintaxe

        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

• -?
  Exibe o resumo da sintaxe de opções osql.

• -L
  Lista os servidores configurados localmente e os nomes dos servidores que estão transmitindo na rede.

  Observação
  Devido à natureza da transmissão em redes, o osql pode não receber a tempo uma resposta de todos os servidores. Assim, a lista de servidores retornada pode variar para cada invocação dessa opção.

• -Ulogin_id
  É a identificação de logon do usuário. IDs de logon diferenciam maiúsculas de minúsculas.

• -Ppassword
  É uma senha especificada pelo usuário. Se a opção -P não for usada, o osql solicitará a senha. Se a opção -P for usada ao término do prompt de comando sem uma senha, o osql usará a senha padrão (NULL).

  Observação sobre segurança
  Não use uma senha em branco. Use uma senha forte. Para obter mais informações, consulte Senhas fortes.

  Senhas diferenciam maiúsculas de minúsculas.

  A variável de ambiente OSQLPASSWORD permite definir uma senha padrão para a sessão atual. Assim, senhas não têm de ser codificadas em arquivos em lote.

  Se você não especificar uma senha com a opção -P, o osql verificará primeiro a variável OSQLPASSWORD. Se nenhum valor for definido, o osql usará a senha padrão, NULL. O exemplo seguinte define a variável OSQLPASSWORD em um prompt de comando e então acessa o utilitário osql:

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

  Observação sobre segurança
  Para mascarar a senha, não especifique a opção -P junto com a opção -U. Em vez disso, depois de especificar o osql junto com a opção -U e outras (não especificar a opção -P), pressione ENTER e o osql pedirá uma senha. Esse método garante que sua senha será mascarada quando for inserida.

• -E
  Usa uma conexão confiável em vez de pedir uma senha.

• -Sserver_name[ **\instance_name]
  Especifica uma instância do SQL Server a qual se conectar. Especifique o server_name para se conectar à instância padrão do SQL Server nesse servidor. Especifique o server_name\**instance_name para se conectar a uma instância nomeada do SQL Server nesse servidor. Se nenhum servidor for especificado, o osql se conectará à instância padrão do SQL Server no computador local. Essa opção é obrigatória quando o osql é executado de um computador remoto na rede.

• -Hwksta_name
  É um nome de estação de trabalho. O nome de estação de trabalho é armazenado em sysprocesses.hostname e exibido pelo sp_who. Se essa opção não for especificada, o nome do computador atual será presumido.

• -ddb_name
  Emite uma instrução USE db_name quando o osqlé iniciado.

• -ltime_out
  Especifica o número de segundos antes de um logon do osql expirar. O tempo limite padrão de logon do osql é de oito segundos.

• -ttime_out
  Especifica o número de segundos antes de um comando expirar. Se não for especificado um valor de time_out, os comandos não vão expirar.

• -hheaders
  Especifica o número de linhas a imprimir entre cabeçalhos de coluna. O padrão é imprimir títulos uma vez para cada conjunto de resultados de consulta. Use -1 para especificar que nenhum cabeçalho será impresso. Se -1 for usado, não deve haver nenhum espaço entre o parâmetro e a configuração (-h-1, não -h -1).

• -scol_separator
  Especifica o caractere do separador de colunas que, por padrão, é um espaço em branco. Para usar um caractere com um significado especial para o sistema operacional como, por exemplo, | ; & < >), coloque-o entre aspas duplas (").

• -wcolumn_width
  Permite ao usuário definir a largura da tela de saída. O padrão é de 80 caracteres. Quando uma linha de saída alcança sua largura de tela máxima, ela é quebrada em várias linhas.

• -apacket_size
  Permite solicitar um pacote de tamanho diferente. Os valores válidos de packet_size são de 512 a 65535. O valor padrão osql é o padrão do servidor. Um tamanho de pacote maior pode aumentar o desempenho na execução de scripts maiores, em que a quantidade de instruções SQL entre comandos GO é substancial. Testes da Microsoft indicam que 8192 geralmente é a configuração mais rápida para operações de cópia em massa. Um tamanho de pacote maior pode ser solicitado, mas o osql assumirá como padrão o padrão do servidor se a solicitação não puder ser atendida.

• -e
  Duplica a entrada.

• -I
  Ativa a opção de conexão QUOTED_IDENTIFIER.

• -Ddata_source_name
  Conecta-se a uma fonte de dados ODBC que é definida usando o driver ODBC do SQL Server. A conexão osql usa as opções especificadas na fonte de dados.

  Observação
  Essa opção não trabalha com fontes de dados definidas para outros drivers.

• -ccmd_end
  Especifica o terminador de comando. Por padrão, comandos são encerrados e enviados ao SQL Server se GO for inserido sozinho em uma linha. Quando você redefinir o terminador de comando, não use palavras reservadas do Transact-SQL nem caracteres que tenham significado especial para o sistema operacional, sejam ou não precedidos por uma barra invertida.

• -q "query"
  Executa uma consulta quando o osql inicia, mas não encerra o osql quando a consulta é concluída. (Observe que a instrução de consulta não deve incluir a instrução GO). Se você emitir uma consulta de um arquivo em lote, use %variáveis ou %variáveis% de ambiente. Por exemplo:

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

  Coloque a consulta entre aspas duplas e qualquer coisa incorporada na consulta entre aspas simples.

• -Q"query"
  Executa uma consulta e imediatamente encerra o osql. Coloque a consulta entre aspas duplas e qualquer coisa incorporada na consulta entre aspas simples.

• -n
  Remove a numeração e o símbolo de prompt (>) das linhas de entrada.

• -merror_level
  Personaliza a exibição de mensagens de erro. São exibidos o número da mensagem, o estado e o nível de erros com o nível de severidade especificado ou superior. Nada é exibido para erros de níveis abaixo do nível especificado. Use -1 para especificar que todos os cabeçalhos retornem com mensagens, até mesmo mensagens informativas. Se -1 for usado, não deverá haver espaço entre o parâmetro e a configuração (-m-1, não -m -1).

• -r { 0| 1}
  Redireciona a saída da mensagem para a tela (stderr). Se você não especificar um parâmetro ou especificar 0, serão redirecionadas somente mensagens de erro com nível de severidade 11 ou superior. Se você especificar 1, serão redirecionadas todas as saídas da mensagem, inclusive "print".

• -iinput_file
  Identifica o arquivo que contém um lote de instruções SQL ou procedimentos armazenados. O operador de comparação menor que (<) pode ser usado no lugar de -i.

• -ooutput_file
  Identifica o arquivo que recebe a saída do osql. O operador de comparação maior que (>) pode ser usado no lugar de -o.

  Se o input_file não for Unicode e -u não for especificado, o output_file será armazenado no formato OEM. Se o input_file for Unicode ou -u for especificado, o output_file será armazenado em formato Unicode.

• -p
  Imprime estatísticas de desempenho.

• -b
  Especifica que o osql é encerrado e retorna um valor DOS ERRORLEVEL no caso de erro. O valor retornado à variável DOS ERRORLEVEL será 1 quando a mensagem de erro do SQL Server tiver um nível de severidade de 11 ou superior, caso contrário, o valor retornado será 0. Arquivos em lote do Microsoft MS-DOS podem testar o valor de DOS ERRORLEVEL e tratar o erro adequadamente.

• -u
  Especifica que o output_file é armazenado em formato Unicode, independentemente do formato do input_file.

• -R
  Especifica que o driver ODBC do SQL Server usa configurações de cliente ao converter dados de moeda, data e hora em dados de caractere.

• -O
  Especifica que certos recursos do osql sejam desativados para corresponder ao comportamento de versões anteriores do isql. Estes recursos são desativados:

  • Processamento em lotes de EOF

  • Escalonamento automático da largura do console

  • Mensagens largas

  Também define o valor DOS ERRORLEVEL padrão como -1.

Observação
As opções -n, -O e -D já não têm suporte do osql.

Comentários

O utilitário osql é iniciado diretamente do sistema operacional com as opções que diferenciam maiúsculas de minúsculas listadas aqui. Depois que o osqlé iniciado, ele aceita instruções SQL e as envia interativamente ao SQL Server. Os resultados são formatados e exibidos na tela (stdout). Use QUIT ou EXIT para sair do osql.

Se você não especificar um nome de usuário ao iniciar o osql, o SQL Server fará a verificação e usará variáveis de ambiente, como osqluser=(user) ou osqlserver=(server). Se nenhuma variável de ambiente for definida, o nome de usuário da estação de trabalho será usado. Se você não especificar um servidor, o nome da estação de trabalho será usado.

Se as opções -U ou -P não forem usadas, o SQL Server tentará conectar usando o Modo de Autenticação do Microsoft Windows. A autenticação baseia-se na conta do Microsoft Windows do usuário que está executando o osql.

O utilitário osql usa a API ODBC. O utilitário usa as configurações padrão do driver ODBC do SQL Server para as opções de conexão ISO do SQL Server. Para obter mais informações, consulte Efeitos de Opções ANSI.

Observação
O utilitário osql não oferece suporte a tipos de dados CLR definidos pelo usuário. Para processar esses tipos de dados, você deve usar o utilitário sqlcmd. Para obter mais informações, consulte Utilitário sqlcmd.

Comandos OSQL

Além das instruções Transact-SQL dentro do osql, os comandos a seguir também estão disponíveis.

Comando	Descrição
GO	Executa todas as instruções inseridas depois do último GO.
RESET	Apaga as instruções inseridas.
QUIT ou EXIT( )	Sai do osql.
CTRL+C	Finaliza uma consulta sem sair do osql.

Observação
Os comandos !! e ED já não têm suporte do osql.

Os terminadores de comando GO (por padrão), RESET EXIT, QUIT e CTRL+C só serão reconhecidos se forem exibidos no início de uma linha, imediatamente depois do prompt do osql.

GO sinaliza tanto o término de um lote quanto a execução de qualquer instrução de cachê do Transact-SQL. Quando você pressiona ENTER ao término de cada linha de entrada, o osql armazena as instruções nessa linha em cache. Quando você pressiona ENTER depois de digitar GO, todas as instruções atualmente em cache são enviadas como um lote ao SQL Server.

O utilitário osql atual funciona como se houvesse um comando GO implícito ao final de qualquer script executado, portanto todas as instruções no script são executadas.

Termine um comando digitando um começo de linha com um terminador de comando. Você pode seguir o terminador de comando com um inteiro para especificar quantas vezes o comando deve ser executado. Por exemplo, para executar esse comando 100 vezes, digite:

SELECT x = 1
GO 100

Os resultados são impressos uma vez ao final da execução. O osql não aceita mais de 1.000 caracteres por linha. Instruções grandes devem ser divididas em várias linhas.

Os recursos de rechamada de comando do Windows podem ser usados para chamar novamente e modificar instruções osql. O buffer de consulta existente pode ser desmarcado digitando RESET.

Ao executar procedimentos armazenados, o osql imprime uma linha em branco entre cada conjunto de resultados em um lote. Além disso, a mensagem "0 linhas afetadas" não aparece quando não se aplica à instrução executada.

Usando o osql interativamente

Para usar o osql interativamente, digite o comando osql (e quaisquer opções) em um prompt de comando.

Você pode ler em um arquivo contendo uma consulta (como Stores.qry) para execução pelo osql digitando um comando semelhante a este:

osql -E -i stores.qry

Você pode ler em um arquivo contendo uma consulta (como Titles.qry) e direcionar os resultados a outro arquivo digitando um comando semelhante a este:

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

Observação sobre segurança
Quando possível, use a opção -E(conexão confiável).

Ao usar o osql interativamente, você pode ler um arquivo do sistema operacional no buffer de comandos com o :rfile_name. Isso envia o script SQL no file_name diretamente para o servidor como um único lote.

Observação
Ao usar o osql, SQL Server trata o separador em lote GO, se ele for exibido em um arquivo de script SQL, como um erro de sintaxe.

Inserindo comentários

Você pode incluir comentários em uma instrução Transact-SQL enviada ao SQL Server pelo osql. São permitidos dois tipos de estilos de comentário: -- e /*...*/.

Para obter mais informações, consulte Usando comentários.

Usando EXIT para retornar resultados no osql

Você pode usar o resultado de uma instrução SELECT como o valor de retorno do osql. Se for numérico, a última coluna da última linha do resultado será convertida em um inteiro de 4 bytes (longo). O MS-DOS transmite o byte baixo para o processo pai ou nível de erro do sistema operacional. O Windows passa o número inteiro de 4 bytes. A sintaxe é:

EXIT ( < query > )

Por exemplo:

EXIT(SELECT @@ROWCOUNT)

É possível incluir também o parâmetro EXIT como parte de um arquivo em lote. Por exemplo:

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

O utilitário osql passa tudo entre os parênteses ( ) para o servidor exatamente como digitado. Se um procedimento de sistema armazenado selecionar um conjunto e retornar um valor, somente a seleção será retornada. A instrução EXIT**(** ) sem nada entre os parênteses executa tudo que a precede no lote e é encerrada sem valor de retorno.

Há quatro formatos EXIT:

• EXIT

Observação
Não executa o lote; sai imediatamente e não retorna valor algum.

• EXIT**(** )

Observação
Executa o lote e então sai imediatamente e não retorna valor algum.

• EXIT**(query)**

Observação
Executa o lote, incluindo a consulta, e sai depois de retornar os resultados da consulta.

• RAISERROR com estado de 127

Observação
Se for usado RAISERROR em um script osql e ocorrer um estado 127, o osql sairá e retornará a ID da mensagem para o cliente. Por exemplo:

RAISERROR(50001, 10, 127)

Esse erro fará com que o script osql seja encerrado e retorne a ID da mensagem 50001 ao cliente.

Os valores de retorno de -1 a -99 são reservados pelo SQL Server; osql define estes valores:

• -100

  Erro encontrado antes da seleção do valor de retorno.

• -101

  Nenhuma linha encontrada ao se selecionar o valor de retorno.

• -102

  Erro de conversão ao selecionar valor de retorno.

Exibindo Tipos de Dados money e smallmoney

O osql exibe os tipos de dados money e smallmoney com duas casas decimais, embora o SQL Server armazene o valor internamente com quatro casas decimais. Considere o exemplo:

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

Essa instrução produz um resultado de 10.3496, que indica que o valor é armazenado com todas as casas decimais intactas.

Consulte também

Referência

/*...*/ (Comment) (MDX)

-- (Comentário) (MDX)

CAST e CONVERT (Transact-SQL)

RAISERROR (Transact-SQL)