CANCEL_UC_OBJECT

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

Notes:

The script function causes all open transactions of the script to be written 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_OBJECTscript function.

Syntax

CANCEL_UC_OBJECT (RunID [, Extension])

Parameters

CANCEL_UC_OBJECT
Terminates an object in an active status
RunID
RunID of the active object to terminate
Format: script literal or script variable
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.
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
  Allowed values:
  - ENDED_OK
  - ENDED_CANCEL
  - ENDED_TIMEOUT
- Workflow, Schedule and Group objects only: specify ALL to cancel all running child tasks in the object.

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.

Tip: 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