ACTIVATE_UC_OBJECT

Script Function: Executes an object.

Syntax

ACTIVATE_UC_OBJECT ( Object name [ , , [Logical Date] [ , [TimeZone] [ , [ Start time|Period object] [ , [ PASS_VALUES] [ , [Queue] [ , [Alias] [ , [ENABLE_PROMPTS] ] ] ] ] ] ] ])
ACTIVATE_UC_OBJECT ( Object name [ , [WAIT] [ , [Logical Date] [ , [TimeZone] [ , , [ PASS_VALUES] [ , [Queue] [ , [Alias] [ , [ENABLE_PROMPTS[, FixedTimeValue, [TERMINATE][, Executed-Object] ] ] ] ] ] ] ] ] ])

Syntax

Description/Format

Object Name

The name of the object.
Format: AE name, script literal or script variable

WAIT

The keyword WAIT indicates that the script function waits until the object has ended.

Logical Date

The logical date that should be used when you activate the object in the date format "YYMMDD" or "YYYYMMDD."

Format: script literal or script variable

You can also specify the date in a different date format. You do so by entering the required date format, followed by a separator (: or ;) and then specify the date. The date format is an optional parameter.

TimeZone

The name of a TimeZone object.
TimeZone for time stamp calculation.

Format: script literal or script variable

Start time | Period object

Either a valid time stamp string or the name of an existing period object.

  • Start time: A time stamp that consists of a date and time ("YYYY-MM-DD HH:MM:SS").
    Format: script literal or script variable
  • Period object: A Period object you want to specify for a recurring execution.
  • The parameters Logical Date and Start time are ignored when you define a Period object.

    When the parameter Period object is used, the execution starts once immediately. All subsequent executions start as defined in the Period object's settings.

PASS_VALUES

The keyword PASS_VALUES has the effect that the object variables and PromptSet variables are passed on to the task that should start.

Queue

Specification of a particular Queue object that should be used to restart the task.

The task automatically starts in the Client Queue (CLIENT_QUEUE) if no queue has been specified.

Alias

The alias name for the object that should be activated. It is shown in the Process Monitoring perspective and the statistics instead of the actual object name.
Format: AE name, script literal or script variable

In AE, the same rules apply for alias names and for object names:
Maximum length: 200 characters
Allowed characters: A-Z, 0-9, $, @, _, -, . and #

ENABLE_PROMPTS

Calls the PromptSet input mask of the activated object in the Automic Web Interface.

Requirements:
1) A user is logged on to the Automic Web Interface.
2) The script element must be available in an object that is started by this user.
3) When the script element is called, this user must still be logged on to the Automic Web Interface with the same session ID.

Script processing is neither affected when the above requirements are not met nor when no PrompSet objects are assigned to the object that should be activated. In this case, the input dialogs are just not displayed.

FixedTimeValue

The maximum runtime of the started object.
Format: script literal or script variable

This value must be specified in the time format HH:MM:SS.
MM and SS must be two-digit values, HH can also be a one-digit value.
For example: "1:05:07"

Note that you can only use this parameter in combination with the keyword WAIT.

When you define a maximum runtime, you must also define at least one action that will be processed when the limit is exceeded. You use the parameters TERMINATE and Execute for this purpose.

TERMINATE This parameter cancels the task when the maximum runtime (time limit) is exceeded.
Executed-Object The object that should be activated when the maximum runtime is exceeded.
Format: AE name, script literal or script variable.

Return codes

Run number  (RUN#) of the activated object.
"0" - Activation was not successful.
"20380" - Object was canceled with the script command :EXIT.

Comments

The script function ACTIVATE_UC_OBJECT can be used to execute objects of the object class of executable objects.

The new tasks are immediately launched into the execution queue if no start time been specified. If a particular start time has been defined, the task is scheduled and obtains the status "Waiting for start time".

Execution time and start time can be two different points in time.

You can also activate objects with a logical date. Optionally, you can specify a particular date format. The default date formats that should be used are "YYMMDD" or "YYYYMMDD". Use a colon or semicolon as a separator between the date format and the date.

When you use the keyword WAIT, you can also define a maximum runtime for the started object (Time Limit). When this limit is exceeded, the task will abort and/or any other object of your choice will be activated. For this purpose, you must define at least one of the two actions by using the parameters TERMINATE and Run.

After a successful activation, the script function returns the object's RUN#. If the option "Generate at Runtime" is unchecked in the called object the script function returns after the generation phase of that object.

Always query the return code. You can analyze error causes by using the script statement :ON_ERROR and the script functions for error handling.

Situation

Return code

Description

General

 

 

Object activation was successful

RUN#

This is the normal case.

Object does not exist

0

Object could not be found. Activation is not possible.

No object execution rights

0

The authorization system checks whether the user who has activated the object is authorized to execute it.

Object activation aborted

0

Tasks can be aborted either manually or through other tasks.

The starting point lies in the past.

Run#

A statistic record with "ENDED_TIMEOUT - Starttime exceeded" is created.

Script generation at activation

 

 

Scripting error in object

0

Scripting errors cause the object activation to be aborted.

:EXIT 0

RUN#

This statement does not abort script processing, it terminates it. It is not handled as an error.

:EXIT <> 0

0

This statement cancels the activation of the object.

:STOP NOMSG

RUN#

This statement does not abort script processing, it terminates it. It is not handled as an error.

:STOP MSG

0

This statement cancels the activation of the object.

Script generation at runtime

 

 

Scripting error in object

RUN#

If "Generate at runtime" has been specified in the object that should be activated, script execution does not take place during the activation process and ACTIVATE_UC_OBJECT cannot identify errors that occur. The RUN# is returned such a case.

:EXIT 0

RUN#

:EXIT <> 0

RUN#

:STOP MSG

RUN#

:STOP NOMSG

RUN#

Post process

 

 

Scripting error in object

RUN#

Post scripts are processed when the execution has ended. They are not part of the activation and errors are not identified.

To prevent endless loops in the Automation Engine, the MAX_NESTING_DEPTH variable in the UC_SYSTEM_SETTINGS - System-Wide Settings allows you to perform a security check to limit the number of recursive object activations. By default, the 16th attempt to activate an object is canceled with the status FAULT_OTHER. Setting the value to 0 (zero) disables the security check.
The limit also applies to recursive workflow activations or a mix of workflow activations and object activations.
For example:
A workflow activates a script which in turn activates the workflow again. If this happens 5 times in a loop (3 times 5 is 15), the 16th activation will be canceled.

Note that you cannot use the parameter WAIT in combination with a start time.

 A particular order is required for the parameters of this script function. Therefore, you must set commas if parameters are omitted (see examples below).

This script statement causes all the script's open transactions to be written to the AE database.

Examples

The first example activates the job "Status" and checks the return code.

:SET &ACTOBJ# = ACTIVATE_UC_OBJECT(STATUS)

:
IF &ACTOBJ# = "0"
:   
SET &ERRNR# = SYS_LAST_ERR_NR()
:   
SET &ERRINS#  = SYS_LAST_ERR_INS()
:   
SET &MESSAGE# = GET_MSG_TXT(&ERRNR#,&ERRINS#)
:   
SET &RET# = SEND_MAIL("john.smith@automic.com",,&MESSAGE#, "Please check. Thank you!")
:
ENDIF

The second example activates the job with a logical date.

:SET &ACTOBJ# = ACTIVATE_UC_OBJECT(STATUS,,"DD.MM.YY:01.12.15"

The workflow MM.WEEK is supposed to run in mid-July at 6 p.m. in the evening.

:SET &ACTOBJ# = ACTIVATE_UC_OBJECT(MM.WEEK,,, "MEZ", "2015-07-15 18:00:00")

Object variables should also be inherited  to the job MM.END.PROCESSING.

:SET &ACTOBJ# = ACTIVATE_UC_OBJECT("MM.END.PROCESSING",,,,, PASS_VALUES)

See also:

Script element Description

RESTART_UC_OBJECT

Repeats the execution of a task.
CANCEL_UC_OBJECT Terminates an activated object.
GET_UC_OBJECT_NR Returns the RUN# of an activated object.
CREATE_OBJECT Creates an object (only Calendar, Login or Variable).
:ON_ERROR Determines the reaction to certain errors and messages of script elements.

Script Elements - Activate Objects

Sample Collection:
Notification with Variable Message Text

Database Maintenance with Options

Retrieving Error Message and Number

Reaction to external Events

About Scripts
Script Elements - Alphabetical Listing

Script Elements - Ordered by Function