CANCEL_UC_OBJECT

Use the CANCEL_UC_OBJECT script function to terminate an active object.

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 active object

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

  • Events 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

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

See also: