%Status e Exceptions do IRIS

Você pode encontrar erros durante qualquer ponto da execução do programa, e existem várias maneiras de levantar e tratar essas exceções. Neste artigo, exploraremos como as exceções são tratadas de forma eficiente no IRIS.

Um dos tipos de retorno mais comumente usados é %Status, que é usado por métodos para indicar sucesso ou falha. Vamos começar discutindo os valores de %Status.

Trabalhando com %Status

O tipo de retorno %Status é usado para representar erros ou sucesso. Muitos métodos do sistema retornam %Status quando ocorre um erro. Você pode criar uma estrutura semelhante para os erros do seu aplicativo ou converter para %Status, mesmo quando você levantou exceções em seu código.

Vamos começar a criar os erros.

Macros

Quando falamos sobre erros, as Macros são essenciais e facilitam a criação de valores de Status no código. O IRIS fornece várias macros para criar e tratar erros dentro do código do seu aplicativo.

A macro mais comumente usada é $$$ERROR.

$$$ERROR

A macro $$$ERROR é especificamente projetada para gerar e retornar um valor %Library.%Status. É sua responsabilidade verificar o status antes de continuar a execução do seu programa. Esta macro está intimamente ligada a erros gerais do sistema. Tenha os seguintes pontos em mente ao usar esta macro:

-O primeiro argumento (códigos de erro) se refere aos códigos de erro gerais dentro do arquivo include %occErrors.
-Se você estiver usando erros predefinidos desse arquivo include, você pode usar a macro diretamente, com ou sem argumentos adicionais.

Observação: Antes de prosseguir, $SYSTEM.OBJ.DisplayError(status) ou $SYSTEM.Status.DisplayError(status)eram usados para exibir o(s) erro(s) e oferecem suporte à localização de strings. 

Set sc = $$$ERROR($$$NamespaceDoesNotExist,"TEST")
Do $SYSTEM.OBJ.DisplayError(sc)

output: ERROR #5015: Namespace 'TEST' does not exist1
ObjectScript
ObjectScript

Set sc = $$$ERROR($$$UserCTRLC)
Do $SYSTEM.OBJ.DisplayError(sc)

ouput: ERROR #834: Login aborted1
ObjectScript
ObjectScript

Se você usar qualquer outro código de erro que não esteja listado em %occErrors, um erro "Código de status desconhecido" será retornado. Sempre use o código de erro predefinido $$$GeneralError == 5001 para mensagens de erro gerais.

Exemplo de código de status desconhecido

Set sc = $$$ERROR(95875,"TEST Error")
Do $SYSTEM.Status.DisplayError(sc)

output: ERROR #95875: Unknown status code: 95875 (TEST Error)
ObjectScript
ObjectScript

Set sc = $$$ERROR($$$GeneralError,"TEST Error")
Do $SYSTEM.OBJ.DisplayError(sc)

output: ERROR #5001: TEST Error
ObjectScript
ObjectScript

$$$ADDSC

O %Status não contém necessariamente apenas um erro. Seu programa pode validar várias condições e manter o controle de todos os erros em um único status, e então usar a macro $$$ADDSC. Por exemplo, o método %ValidateObject() pode retornar múltiplos erros em uma única resposta, que usa essa funcionalidade.

A macro $$$ADDSC anexa um status a outro, e o método $SYSTEM.Status.AppendStatus executa a mesma função.

$$$ADDSC(sc1,sc2) / $SYSTEM.Status.AppendStatus(s1,s2) - anexa sc2 a sc1 e retorna um novo código de status.

ClassMethod AppendErrors()
{
    Set sc1 = $$$ERROR($$$UserCTRLC) 
    Set sc2 = $$$ERROR($$$NamespaceDoesNotExist,"TEST")
    Set sc = $$$ADDSC(sc1,sc2)
    Do $SYSTEM.Status.DisplayError(sc)
    Write !
    Set sc = $$$ADDSC(sc1,sc2)
    Do $SYSTEM.Status.DisplayError(sc)
}
output
LEARNING>do ##class(Learning.ErrorHandling).AppendErrors()
 
ERROR #834: Login aborted
ERROR #5015: Namespace 'TEST' does not exist
 
ERROR #834: Login aborted
ERROR #5015: Namespace 'TEST' does not exist
ObjectScript
ObjectScript

ambos os resultados são iguaias!

$$$GETERRORCODE

$$$GETERRORCODE(status) - Retorna o valor do código de erro do Status. Esta macro pertence ao arquivo %occStatus.inc

    Set status = $$$ERROR($$$UserCTRLC) 
    Write $$$GETERRORCODE(status),!
    #;output: 834
    Set status = $$$ERROR($$$GeneralError,"TEST Error")
    Write $$$GETERRORCODE(status)
    #;output: 5001
ObjectScript
ObjectScript

$$$GETERRORMESSAGE
$$$GETERRORMESSAGE(sc,num) - Esta macro retorna a parte do erro baseada no número (num) no %Status.
Aqui está um exemplo.

ClassMethod GetErrorMsgMacro()
{
	Set status = $$$ERROR($$$GeneralError,"TEST Error",1,$$$ERROR($$$GeneralError,"TEST Error2"))
	write $$$GETERRORMESSAGE(status),! ; It prints "TEST Error"
	#;
	Set st = $$$GETERRORMESSAGE(status,3) ; it get the "$$$ERROR($$$GeneralError,"TEST Error2")" in 3rd position based on the 2nd argument 
	write $$$GETERRORMESSAGE(st),! ; it prints TEST Error2
}

LEARNING>Do ##class(Learning.myexcept).GetErrorMsgMacro()
TEST Error
TEST Error2
ObjectScript
ObjectScript

 

Validar Status de Retorno

Agora que você criou o erro e o retornou para o seu programa, o próximo passo é validar se a resposta de retorno é bem-sucedida ou errônea.

A macro $$$ISERR verifica se o status representa um erro. Ela retorna 1 se o status indicar um erro, caso contrário, retorna 0. Existe outra macro, $$$ISOK, que retorna 1 quando o status é bem-sucedido.

Exibindo Erros

Se o seu programa apresentar erros inesperadamente (sempre espere o inesperado), você precisa exibir a mensagem de erro. A classe %SYSTEM.Status é especificamente projetada para visualizar ou criar valores %Status (se você preferir não usar macros) e já vimos os exemplos acima.

Aqui estão os métodos equivalentes em %SYSTEM.Status que substituem as macros:

As exceções continuarão no próximo artigo.