sp_OAGetProperty (Transact-SQL)

Obtém um valor de propriedade de um objeto OLE.

Convenções da sintaxe Transact-SQL

Sintaxe

sp_OAGetProperty objecttoken , propertyname 
    [ , propertyvalue OUTPUT ]
    [ , index...] 

Argumentos

• objecttoken
  É o token de objeto de um objeto OLE que foi criado anteriormente usando sp_OACreate.

• propertyname
  É o nome de propriedade do objeto OLE a ser retornado.

• propertyvalue OUTPUT
  É o valor de propriedade retornado. Se for especificado, deverá ser uma variável local do tipo de dados apropriado.

  Se a propriedade retornar um objeto OLE, propertyvalue deve ser uma variável local do tipo de dados int. Um token de objeto é armazenado na variável local e pode ser usado com outros procedimentos armazenados de automação OLE.

  Se a propriedade retornar um único valor, especifique uma variável local para propertyvalue, o que retorna o valor de propriedade do método na variável local; ou não especifique propertyvalue, o que retorna o valor de propriedade do método para o cliente como um conjunto de resultados com uma coluna e uma linha.

  Quando a propriedade retornar uma matriz, se propertyvalue for especificado, será definido como NULL.

  Se propertyvalue for especificado, mas a propriedade não retornar um valor, ocorrerá um erro. Se a propriedade retornar uma matriz com mais de duas dimensões, ocorrerá um erro.

• index
  É um parâmetro de índice. Se for especificado, index deverá ser um valor do tipo de dados apropriado.

  Algumas propriedades têm parâmetros. Estas propriedades são chamadas de propriedades indexadas e os parâmetros são chamados de parâmetros de índice. Uma propriedade pode ter vários parâmetros de índice.

  Observação
  Os parâmetros deste procedimento armazenado são especificados por posição, não por nome.

Valores de código de retorno

0 (êxito) ou um número diferente de zero (falha) que é o valor inteiro do HRESULT retornado pelo objeto de Automação OLE.

Para obter mais informações sobre Códigos de Retorno HRESULT, consulte Informações sobre erros e códigos de retorno de automação OLE.

Conjuntos de resultados

Se a propriedade retornar uma matriz com uma ou duas dimensões, a matriz será retornada ao cliente como um conjunto de resultados:

• Uma matriz unidimensional é retornada ao cliente como um conjunto de resultados de uma linha, com tantas colunas quanto houver elementos na matriz. Em outras palavras, a matriz é retornada como colunas.

• Uma matriz bidimensional é retornada ao cliente como um conjunto de resultados com tantas colunas quanto houver elementos na primeira dimensão da matriz e com tantas linhas quanto houver elementos na segunda dimensão da matriz. Em outras palavras, a matriz é retornada como (colunas, linhas).

Quando o valor de retorno de uma propriedade ou o valor de retorno de um método for uma matriz, sp_OAGetProperty ou sp_OAMethod retornará um conjunto de resultados ao cliente. (Os parâmetros de saída de método não podem ser matrizes.) Esses procedimentos examinam todos os valores de dados na matriz para determinar os tipos de dados apropriados do SQL Server e os tamanhos dos dados a serem usados para cada coluna no conjunto de resultados. Para uma coluna específica, esses procedimentos usam o tipo de dados e o tamanho necessários para representar todos os valores de dados nesta coluna.

Quando todos os valores de dados em uma coluna compartilharem o mesmo tipo de dados, esse tipo de dados será usado para a coluna inteira. Quando os valores de dados em uma coluna forem de tipos de dados diferentes, o tipo de dados da coluna inteira será escolhido com base no quadro a seguir.

Comentários

Você também pode usar sp_OAMethod para obter o valor de uma propriedade.

Permissões

Exige associação à função de servidor fixa sysadmin.

Exemplos

A.Usando uma variável local

O exemplo a seguir obtém a propriedade HostName (do objeto SQLServer criado anteriormente) e a armazena em uma variável local.

DECLARE @property varchar(255)
EXEC @hr = sp_OAGetProperty @object, 'HostName', @property OUT
IF @hr <> 0
BEGIN
   EXEC sp_OAGetErrorInfo @object
    RETURN
END
PRINT @property

B.Usando um conjunto de resultados

O exemplo a seguir obtém a propriedade HostName (do objeto SQLServer criado anteriormente) e a retorna ao cliente como um conjunto de resultados.

EXEC @hr = sp_OAGetProperty @object, 'HostName'
IF @hr <> 0
BEGIN
   EXEC sp_OAGetErrorInfo @object
    RETURN
END

Consulte também

Referência

Procedimentos armazenados de automação OLE (Transact-SQL)

Script de exemplo de automação OLE