.. _error:

=====
error
===== 

Dispara um erro personalizado

Descrição
~~~~~~~~~
A função fn:error interrompe a execução da consulta com uma mensagem de erro 
específica. Isso é útil quando aparece uma condição inesperada ou inválida, como 
um dado ausente ou inválido. Você pode chamar fn:error na consulta para avisar 
quem a usa desses problemas.

Como o processador usa os argumentos opcionais $description e $error-object 
depende da implementação. A maioria dos processadores mostra $description como 
parte da mensagem de erro.

Alguns processadores mostram o nome do erro como um URI, em que a parte local é 
um identificador de fragmento, como em http://datypic.com/err#ProdNumReq.

A função fn:error é a mesma que o processador chama implicitamente sempre que 
ocorre um erro durante a avaliação. O tipo de retorno none só é usado pela 
fn:error e não está disponível para quem escreve consultas. Significa apenas que 
fn:error nunca devolve valor: a avaliação para assim que ela é chamada.

.. list-table::
   :widths: 40 60
   :header-rows: 1

   * - **Parâmetros**
     - **Descrição**
   * - error:string()
     - um nome qualificado para o erro
   * - description:string()
     - uma descrição do erro
   * - error-object:item()
     - o item ou os itens que causaram o erro

Exemplos
~~~~~~~~
.. list-table::
   :widths: 25 25 50
   :header-rows: 1

   * - **XPath**
     - **Resultado**
     - **Explicação**
   * - error()
     - Error
     - Dispara o erro genérico FOER0000.
   * - error(xs:QName('dty:ProdNumReq'))
     - Error
     - Supõe que o prefixo dty foi declarado.
   * - error(QName('http://datypic.com/err', 'ProdNumReq'), 'Missing number.')
     - Error
     - Dispara o erro ProdNumReq no namespace http://datypic.com/err, com uma mensagem.
   * - error(QName('http://datypic.com/err', 'ProdNumReq'), 'Missing number.', $prod)
     - Error
     - Igual ao anterior, passando também $prod como informação adicional para quem trata o erro.