sp_OAGetProperty (Transact-SQL)

Aplica-se a:SQL Server

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

Convenções de sintaxe de 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.

propertyvalueSAÍDA
É 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 deverá ser uma variável local do tipo de dados int. Um token de objeto é armazenado na variável local e esse token de objeto 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, que retorna o valor da propriedade na variável local, ou não especifique propertyvalue, que retorna o valor da propriedade para o cliente como um conjunto de resultados de uma única coluna e linha única.

Quando a propriedade retorna uma matriz, se propertyvalue for especificado, ela será definida 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 especificado, o índice deve 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 do 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 Códigos de retorno de automação OLE e informações de erro.

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 um valor de retorno de propriedade ou valor de retorno de método é uma matriz, sp_OAGetProperty ou sp_OAMethod retorna um conjunto de resultados para o cliente. (Os parâmetros de saída do método não podem ser matrizes.) Esses procedimentos examinam todos os valores de dados na matriz para determinar os tipos de dados e comprimentos de dados apropriados do SQL Server 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.

	INT	FLOAT	money	datetime	varchar	nvarchar
int	int	float	money	varchar	varchar	nvarchar
float	float	float	money	varchar	varchar	nvarchar
money	money	money	money	varchar	varchar	nvarchar
datetime	varchar	varchar	varchar	datetime	varchar	nvarchar
varchar	varchar	varchar	varchar	varchar	varchar	nvarchar
nvarchar	nvarchar	nvarchar	nvarchar	nvarchar	nvarchar	nvarchar

Comentários

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

Permissões

Requer associação à função de servidor fixa sysadmin ou permissão de execução diretamente neste Procedimento Armazenado. Ole Automation Procedures a configuração deve estar habilitada para usar qualquer procedimento do sistema relacionado à automação OLE.

Exemplos

R. Usando uma variável local

O exemplo a seguir obtém a propriedade (do objeto SQLServer criado anteriormente) e a HostName 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 (do objeto SQLServer criado anteriormente) e a HostName retorna ao cliente como um conjunto de resultados.

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

Confira também

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