Script Function: Activates an objectAutomation Engine controlled activities and processes are structured in the form of objects. See also: Task.
ACTIVATE_UC_OBJECT(Object name, [WAIT], [Logical Date], [TimeZone],
Syntax |
Description/Format |
---|---|
Object Name |
The name of the object. |
WAIT |
The keyword WAIT indicates that the script functionPre-defined run book template in the Automation Engine. One single step only, e.g. Start Windows Service, Copy file,… 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 literalor 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. Format: script literal or script variable |
Start time | Period object |
Either a valid time stamp string or the name of an existing period object.
The parameters Logical Date and Start time are ignored when you define a Period object. |
PASS_VALUES |
The keyword PASS_VALUES has the effect that the object variables and PromptSet variables are passed on to the taskAn executable object that is running. Tasks are also referred to as activities. that should start. |
Queue |
Specification of a particular Queue object that should be used to restartA restart refers to the repetition of an object's execution. This action differs from a new start in some parts. the task. The task automatically starts in the Client Queue (CLIENT_QUEUE) if no queueA particular Automation Engine (AE) object type. In AE, a queue determines the maximum number of concurrent tasks, their priorities and the order in which tasks should be executed. In ARA, queues are containers for workflow executions that should be executed at a certain time one after another. has been specified. |
Alias |
The alias name for the object that should be activated. It is shown in the Activity Window and the statisticsThis is a list of a task's previous runs. instead of the actual object name. In AE, the same rules apply for alias names and for object names: |
ENABLE_PROMPTS |
Calls the PromptSet input mask of the activated object in the UserInterfaceThis is the Automation Engine's graphical user interface. [Formerly called the "Rich Client", "RichGUI" and "Dialog Client."]. Requirements: 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. |
Time Limit |
The maximum runtimeThe duration of a task's execution. It refers to the period between a task's start and end. It does not include its activation period (see also: activation and start). of the started object. This value must be specified in the time format HH:MM:SS. 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 actionActions are predefined building blocks for recurring activities. They are commonly used for managing third party systems or in deployment scenarios. 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. |
Run | 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. |
If the script terminates with FAULT_OTHER, it writes messages like the following to the Message window:
13.10.2015 14:08:04 - U0012112 Task 'OBJECT' (RunID '0101419720') terminated with script error.
13.10.2015 14:08:04 - U0020423 Runtime error in object 'OBJECT', line '00002': object must not activate itself (endless loop)
The script function ACTIVATE_UC_OBJECT can be used to activate objects of the object class of executable objects.
Objects are immediately activated if no start time been specified. If a particular start time has been defined, the task is scheduled and obtains the statusThis represents the condition of a task (such as active, blocked, generating). "Waiting for start time".
Activation and start time can be two different points in time.
You can also activate objects with a logical dateThe logical date is used as a comparison date for checking Calendar conditions.. 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#. Return code "0" is supplied if an error has occurred.
Always query the return codeThe value that represents the result of tasks and script functions.. 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 can not 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. |
Objects cannot activate themselves by using this script function. Any attempt to do so results in an infinite loop and could bring the whole AE system to a halt.
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 databaseA database is an organized collection of data including relevant data structures..
The first example activates the jobAn Automation Engine object type for a process that runs on a target system. "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.00")
The workflowAn object of the Automation Engine that can include several executable objects and which runs them in a specified order. [Formerly called "ProcessFlow" and "JobPlan."] MM.WEEK is supposed to run in mid-July at 6 p.m. in the evening.
:SET &ACTOBJ# = ACTIVATE_UC_OBJECT(MM.WEEK,,, "MEZ", "2005-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 |
---|---|
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
Automic Documentation - Tutorials - Automic Blog - Resources - Training & Services - Automic YouTube Channel - Download Center - Support |
Copyright © 2016 Automic Software GmbH |