Retrieving Error Message and Number

Objective: In the case of an error, the particular message text and number are to be retrieved and sent by email.

ScriptEigener Objekttyp in der Automation Engine elements used: ACTIVATE_UC_OBJECT, GET_MSG_TXT, :ON_ERROR, PRINT, SEND_MAIL, SYS_ACT_ME_NAME, SYS_ACT_ME_NR, SYS_LAST_ERR_INS, SYS_LAST_ERR_NR, UC_CRLF, XML_CLOSE, XML_GET_NODE_TEXT and XML_OPEN

Example

If an error occurs while processing a script, a message consisting of text and number is generated. This information can be accessed and the values obtained from there be used later on for reacting to errors that occurred.

Task

The following example shows how to retrieve the full error message and forward it by email.

We start off by activating the object "MM.ENDOFMONTH". As this name is used more than once, a script literal can be defined for it. If activating the object is not possible, the script function ACTIVATE_UC_OBJECT returns the value 0. In this case, the information of the last occurred error can be retrieved.

Use the following script elements:

SYS_LAST_ERR_NR - supplies the error number
SYS_LAST_ERR_INS - supplies the variable part of the error text (e.g. RunID"Kurzform für ""laufende Nummer"". Hierbei handelt es sich genauer um eine Zahl, welche die Durchführung einer Aufgabe eindeutig kennzeichnet. Die RunID kann zwischen 7 und 10 Stellen aufweisen. Sie wird von der Komponente Automation Engine vergeben.")
GET_MSG_TXT - supplies the whole error message text which consists of the error number and the variable part of the message.

The obtained values can be sent to a contact person by email, for example. As responsibilities within an AE system are often shared between several persons, it might be useful to determine one particular contact person. This person's name can then be recorded in the Documentation tab of each object. Object templates are available for the comfortable storage of information. If an object is created with a template, the previously defined contents of this template are assumed.

The following illustration shows a structured-documentation tab. This is especially useful as it can be read with special script elements (XML*).

With the script function XML_GET_NODE_TEXT, you can retrieve the responsible contact person. This person is then the recipient of an email sent with SEND_MAIL. The email contains the name of the object to be started, and the name and RunID of the task in which activation was attempted.

Note for :ON_ERROR:

In some script elements - ACTIVATE_UC_OBJECT is one of them - you can determine whether script processing is aborted in case of an error. In this example, we use ":ON_ERROR RESUME" so that the occurred error can be analyzed. With the use of ":ON_ERROR ABEND", the script would be aborted in the line including ACTIVATE_UC_OBJECT.

The following script shows the whole procedure explained above in detail:

!An email message should be sent
!when the object cannot be activated.

:SET&obj_to_be_started# = 'MM.ENDOFMONTH'

:ON_ERROR RESUME
:SET&start# = ACTIVATE_UC_OBJECT(&obj_to_be_started#)

:IF&start# = 0

: SET&error_nr# = SYS_LAST_ERR_NR()
: SET&error_var# = SYS_LAST_ERR_INS()
: SET&message# = GET_MSG_TXT(&error_nr,&error_var#)
: PRINT'&message#'

!Retrieving the contact person
: SET&xmldocu# = XML_OPEN(,'@Description')
: SET&contact# = XML_GET_NODE_TEXT(&xmldocu#)
: XML_CLOSE

: SET&obj_name# = SYS_ACT_ME_NAME()
: SET&obj_runnr# = SYS_ACT_ME_NR()

!Linebreak
: SET&to# = UC_CRLF()

: SET&ret_mail# = SEND_MAIL('&contact#@automic.at',,'The task &obj_to_be_started# could not be started!','NAME: &obj_name# / RunID: &obj_runnr# &to#&to# MESSAGE: &Message#')

:ENDIF

The E-mail connection of an agent must be active as otherwise, the email cannot be sent!