srv_convert (API de procedimento armazenado estendido)

Importante
Esse recurso será removido em uma versão futura do Microsoft SQL Server. Não utilize esse recurso em desenvolvimentos novos e modifique, assim que possível, 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 é passado para a função de manipulador de erro da API de procedimento armazenado estendido quando ocorre 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 coloca 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 chama o manipulador de erro fornecido pelo usuário, caso haja algum, e retorna -1.

  Caso desttype seja SRVDECIMAL ou SRVNUMERIC, o parâmetro dest deve ser um ponteiro para uma estrutura DBNUMERIC ou DBDECIMAL com os campos de precisão e escala da estrutura já definidos como 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 de tipo SRVCHAR, o valor igual a destlen deve ser o comprimento 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 comprimento igual a -1 faz com que a cadeia de caracteres seja terminada em nulo.

Retorna

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 oferece suporte, ele chama o manipulador de erro fornecido pelo desenvolvedor, caso haja algum, define o número de erro global e retorna -1.

Comentários

A função srv_willconvert determina se uma determinada conversão é 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 no estouro caso o número seja maior que o valor máximo do destino, ou no 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, converter 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 das conversões do tipo de dados da API de procedimento armazenado estendido, consulte Tipos de dados (API de procedimentos armazenados estendidos).

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.

Observação sobre segurança
Você deve examinar cuidadosamente o código-fonte de procedimentos armazenados estendidos e 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.

Consulte também

Referência

srv_setutype (API de procedimento armazenado estendido)

srv_willconvert (API de procedimento armazenado estendido)