IRIS %Status y Excepciones

Podéis encontrar errores en cualquier punto de la ejecución del programa, y hay varias formas de generarlos y manejarlos en IRIS. En este artículo, exploraremos cómo gestionar excepciones de manera eficiente.

Uno de los tipos de retorno más utilizados es %Status, que los métodos emplean para indicar éxito o fallo. Vamos a empezar hablando de los valores de %Status.

Trabajando con %Status

El tipo %Status representa errores o éxito. Muchos métodos del sistema devuelven %Status cuando ocurre un error. Podéis crear una estructura similar para errores en vuestra aplicación o convertir excepciones en %Status dentro del código. Incluso cuando habéis planteado excepciones en el código.

Vamos a empezar creando errores.

Macros

Cuando hablamos de errores, las macros son esenciales y facilitan la creación de valores %Status en el código. IRIS proporciona varias macros para generar y manejar errores dentro de vuestra aplicación.

La macro más utilizada es $$$ERROR.

$$$ERROR

La macro $$$ERROR está diseñada específicamente para generar y devolver un valor %Library.%Status. Es vuestra responsabilidad verificar el estado antes de continuar con la ejecución del programa. Esta macro está estrechamente relacionada con los errores generales del sistema. Tened en cuenta los siguientes puntos al utilizarla:

• El primer argumento (códigos de error) hace referencia a códigos de error generales en el archivo %occErrors.
• Si usáis errores predefinidos de ese archivo, podéis utilizar la macro directamente, con o sin argumentos adicionales.

Nota: Antes de continuar, podéis usar $SYSTEM.OBJ.DisplayError(status) o $SYSTEM.Status.DisplayError(status) para mostrar los errores y admitir la traducción de cadenas de texto para los errores.

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

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

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

ouput: ERROR #834: Login aborted1

Si utilizáis un código de error que no esté listado en %occErrors, se devolverá un error de "Código de estado desconocido" o "Unknown status code". Para mensajes de error generales, usad siempre el código de error predefinido $$$GeneralError == 5001.

Ejemplo de código de estado desconocido

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

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

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

output: ERROR #5001: TEST Error

$$$ADDSC

El %Status no almacena solo un error, sino que puede contener varios. Vuestro programa puede validar múltiples condiciones y registrar todos los errores en un único estado usando la macro $$$ADDSC.Por ejemplo, el método %ValidateObject() puede devolver varios errores en una sola respuesta utilizando esta funcionalidad.

La macro $$$ADDSC agrega un estado a otro, permitiendo combinar múltiples errores en un solo código de estado. El método $SYSTEM.Status.AppendStatus realiza la misma función, facilitando el manejo de múltiples errores en una respuesta unificada.

$$$ADDSC(sc1, sc2) o $SYSTEM.Status.AppendStatus(s1, s2) añaden sc2 a sc1, devolviendo un nuevo código de estado con ambos errores combinados.

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

¡Ambos resultados son lo mismo!

$$$GETERRORCODE

La macro $$$GETERRORCODE(status) devuelve el valor del código de error del %Status. Esta macro pertenece al archivo %occStatus.inc

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

$$$GETERRORMESSAGE
La macro $$$GETERRORMESSAGE(sc, num) devuelve la parte del mensaje de error basado en el número num del %Status. Aquí va un ejemplo.

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

 

Validar un %Status que se ha devuelto como resultado

Ahora que habéis creado el error y lo habéis devuelto a vuestro programa, el siguiente paso es validar si la respuesta devuelta es correcta o errónea.

La macro $$$ISERR comprueba si el estado representa un error. Devuelve 1 si el estado indica un error, en caso contrario devuelve 0. Hay otra macro, $$$ISOK, que devuelve 1 cuando el estado es correcto.

Visualización de errores

Si vuestro programa falla inesperadamente (siempre esperad lo inesperado), necesitáis mostrar el mensaje de error. La clase %SYSTEM.Status está específicamente diseñada para ver o crear valores %Status (si preferís no utilizar macros) y ya hemos visto los ejemplos anteriores.

Aquí hay métodos equivalentes en %SYSTEM.Status que sustituyen a las macros:

Las Excepciones continuarán en el próximo artículo.