srv_convert (API de procedimento armazenado estendido)

Aplica-se a:SQL Server

Importante

Esse recurso será removido em uma versão futura do SQL Server. Evite usar esse recurso em desenvolvimentos novos e planeje modificar os aplicativos que atualmente o utilizam. Use a integração CLR em vez disso.

Altera dados de um tipo de dados para outro.

Sintaxe

  
int srv_convert (  
SRV_PROC *  
srvproc  
,  
int  
srctype  
,  
void *  
src  
,  
DBINT  
srclen  
,  
int  
desttype  
,  
void *  
  dest  
,  
DBINT  
destlen  
);  

Argumentos

srvproc
É um ponteiro para a estrutura SRV_PROC que atua como identificador de uma conexão de cliente específica. A estrutura contém todas as informações de controle que a biblioteca de APIs de procedimento armazenado estendido usa para gerenciar as comunicações e os dados entre o aplicativo e o cliente. Caso o identificador srvproc seja fornecido, ele será passado para a função de manipulador de erro da API de Procedimento Armazenado Estendido quando ocorrer um erro.

srctype
Especifica o tipo de dados dos dados a serem convertidos. Este parâmetro pode ser qualquer um dos tipos de dados da API de procedimento armazenado estendido.

src
Trata-se de um ponteiro para os dados a serem convertidos. Este parâmetro pode ser qualquer um dos tipos de dados da API de procedimento armazenado estendido.

srclen
Especifica o comprimento, em bytes, dos dados a serem convertidos. Caso srclen seja 0, srv_convert colocará um valor nulo na variável de destino. A menos que seja 0, esse parâmetro é ignorado para tipos de dados com comprimento fixo, quando se pressupõe que os dados sejam NULL. Para dados do tipo de dados SRVCHAR, um comprimento igual a -1 indica a cadeia de caracteres é terminada em nulo.

desttype
Especifica o tipo de dados no qual converter a origem. Este parâmetro pode ser qualquer um dos tipos de dados da API de procedimento armazenado estendido.

dest
Trata-se de um ponteiro para a variável de destino que recebe dados convertidos. Caso esse ponteiro seja NULL, srv_convert chamará o manipulador de erro fornecido pelo usuário, se houver, e retornará -1.

Caso desttype seja SRVDECIMAL ou SRVNUMERIC, o parâmetro dest deverá ser um ponteiro para uma estrutura DBNUMERIC ou DBDECIMAL com os campos de precisão e escala da estrutura já definidos com os valores desejados. É possível usar DEFAULTPRECISION para especificar uma precisão padrão, e DEFAULTSCALE para especificar uma escala padrão.

destlen
Especifica o comprimento, em bytes, da variável de destino. Esse parâmetro é ignorado para tipos de dados com comprimento fixo. Para uma variável de destino do tipo SRVCHAR, o valor igual a destlen deve ser o tamanho total do espaço do buffer de destino. Um comprimento igual a -1 para uma variável de destino do tipo SRVCHAR ou SRVBINARY indica se há espaço suficiente disponível. Para uma variável de destino do tipo srvchar, um tamanho igual a -1 faz com que a cadeia de caracteres termine em nulo.

Retornos

O comprimento dos dados convertidos, em bytes, caso a conversão do tipo de dados tenha êxito. Quando srv_convert encontra uma solicitação para uma conversão para a qual não dá suporte, ele chama o manipulador de erro fornecido pelo desenvolvedor, se houver, define um número de erro global e retorna -1.

Comentários

A função srv_willconvert determina se uma conversão específica é permitida.

A conversão para os tipos de dados numéricos aproximados SRVFLT4 ou SRVFLT8 pode resultar em uma certa perda de precisão. A conversão dos tipos de dados numéricos aproximados SRVFLT4 ou SRVFLT8 em SRVCHAR ou SRVTEXT também pode resultar em alguma perda de precisão.

A conversão em SRVFLTx, SRVINTx, SRVMONEY, SRVMONEY4, SRVDECIMAL ou SRVNUMERIC pode resultar em estouro, caso o número seja maior que o valor máximo do destino ou em estouro negativo, caso o número seja menor que o valor mínimo do destino. Caso o estouro ocorra durante a conversão em SRVCHAR ou SRVTEXT, o primeiro caractere do valor resultante contém um asterisco (*) para indicar o erro.

Ao converter SRVCHAR em SRVBINARY, srv_convert interpreta SRVCHAR como hexadecimal, independentemente da cadeia de caracteres conter um 0 à esquerda. Ao converter SRVBINARY em SRVCHAR, srv_convert cria uma cadeia de caracteres hexadecimal sem um 0 à esquerda. Em todos os demais casos, uma conversão para ou do tipo de dados SRVBINARY é uma cópia de bit direta.

Em determinados casos, isso pode ser útil na conversão de um tipo de dados em si mesmo. Por exemplo, a conversão de SRVCHAR em SRVCHAR com destlen igual -1 adiciona um terminador nulo a uma cadeia de caracteres.

Para obter uma descrição dos tipos de dados e conversões de tipo de dados da API de Procedimento de Repositório Estendido, consulte Tipos de dados (API de Procedimento Armazenado Estendido).

A função srv_convert pode falhar por várias razões:

• A conversão solicitada não está disponível.

• A conversão resultou em truncamento, estouro ou perda de precisão na variável de destino.

• Ocorreu um erro de sintaxe durante a conversão de uma cadeia de caracteres em um tipo de dados numérico.

Importante

Você deve examinar totalmente o código-fonte de procedimentos armazenados estendidos e deve testar as DLLs compiladas antes de instalá-las em um servidor de produção. Para obter informações sobre revisão e testes de segurança, consulte este site da Microsoft.

Confira também

srv_setutype (API de procedimento armazenado estendido)
srv_willconvert (API de procedimento armazenado estendido)