CANCEL_UC_OBJECT

Use the CANCEL_UC_OBJECT script function to terminate an object in an active status.

Notes:

This script function writes all open transactions of the script to the AE database. For more information, see Script Processing.
You cannot use CANCEL_UC_OBJECT to deactivate ended tasks. To deactivate an ended task, use the DEACTIVATE_UC_OBJECT script function.

Syntax

CANCEL_UC_OBJECT (RunID [,Extension])

Parameters

Parameter	Description	Format / Allowed Values
RunID	RunID of the active object to terminate. Note: (Events only) A new instance of the active event is created whenever an event occurs. The new instance also has a RunID. Use the SYS_ACT_PARENT_NR script function to retrieve the RunID when you want to terminate the event.	Script literal or script variable
Extension	(Optional) Additional termination options depending on the type of object: Event and Remote Task Manager objects only: Specify the status of the object after termination. Workflow, Schedule and Group objects only: Specify ALL to cancel all running child tasks in the object.	ENDED_OK ENDED_CANCEL ENDED_TIMEOUT ALL

Parameter

Description

Format / Allowed Values

RunID

RunID of the active object to terminate.

Note: (Events only) A new instance of the active event is created whenever an event occurs. The new instance also has a RunID. Use the SYS_ACT_PARENT_NR script function to retrieve the RunID when you want to terminate the event.

Script literal or script variable

Extension

(Optional) Additional termination options depending on the type of object:

Event and Remote Task Manager objects only: Specify the status of the object after termination.
Workflow, Schedule and Group objects only: Specify ALL to cancel all running child tasks in the object.

ENDED_OK
ENDED_CANCEL
ENDED_TIMEOUT
ALL

Return Codes

The script function returns the following codes:

0: Task was successfully canceled
11049: No task with the specified RunID was found, so the task could not be canceled
11050: Task has a status that cannot be canceled
20347: Script was started via a CallAPI and cannot be canceled with the CANCEL_UC_OBJECT function
20002: Runtime error in object '&01', line '&02'. Cancel with status '&04' is only allowed for EVNT and JOBQ.

Important Considerations

Use the :ON_ERROR script statement to define action to take if the cancellation fails. For more information, see Script Elements for Error Handling.

Examples

The following script activates a Notification object that is called ALARM3, and waits 60 seconds. If the Notification is still active after 60 seconds, the Notification is terminated:

:SET &RUNNR# = ACTIVATE_UC_OBJECT("ALARM3")

:WAIT 60

:SET &STATUS# = GET_STATISTIC_DETAIL(&RUNNR#,STATUS)

:IF &STATUS# < 1800

:SET &STATUS# = CANCEL_UC_OBJECT(&RUNNR#)

:ENDIF

The following example shows part of an event process script in an Event object. When the event occurs, the script retrieves the RunID of the parent (the main Event task), and terminates the event:

:SET &RUNNR# = SYS_ACT_PARENT_NR()

:SET &STATUS# = CANCEL_UC_OBJECT (&RUNNR#)

The following lines check if an Event (EVNT.NIGHT) is still active. If the Event is active, the script cancels the Event and sets the status of the task to ENDED_CANCEL:

:SET &RUNNR# = GET_UC_OBJECT_NR(EVNT.NIGHT)

:IF &RUNNR# <> "

:SET &STATUS# = CANCEL_UC_OBJECT(&RUNNR#, "ENDED_CANCEL")

:ENDIF