Automation Engine Script Guide > Ordered by Function > Activation Data > GET_UC_OBJECT_STATUS

GET_UC_OBJECT_STATUS

Script Function: Returns the statusThis represents the condition of a task (such as active, blocked, generating). of an activated objectAutomation Engine controlled activities and processes are structured in the form of objects. See also: Task.

Syntax

GET_UC_OBJECT_STATUS([Object type ], [RunID], [ Request])

Syntax

Description/Format

Object Type

Short for of the object type.
Format: AE name, script literal or script variable

Optional parameter because the object typeAn individual object is provided for the individual activities: There are User, UserGroup, Notification, Cockpit, CodeTable, Documentation, Event, Agent, FileTransfer, Group, Include, Job, Workflow, Calendar, Login, Client, RemoteTaskManager, Schedule, Script, Server, Sync, Variable and TimeZone objects is clearly identified through its RunIDShort for "run number". It is a number that provides unique information about a task's execution. The RunID can include 7 to 10 digits. It is assigned by the Automation Engine component . (compatible with Version 2.6xx).

RunID

Run number of the activated object.
Format: scriptA particular Automation Engine object type. literal or script variableA placeholder for a value within a script.

Request

Information that should be retrieved from the activated object.
Format: script literal or script variable

Allowed values: "STATUS" (default value), "RETCODE", "STATUS_TEXT"

"RETCODE" = Retrieves the return code of the activated object.
"STATUS" = Retrieves the current system return code of the activated object.
"STATUS_TEXT" = Retrieves the status text. This value is only available in jobs on OS agents (for example, the status text cannot be retrieved in SAP jobs.


Return codes

Depending on the specifications made, either the return codeThe value that represents the result of tasks and script functions., status or the status text of the taskAn executable object that is running. Tasks are also referred to as activities. is returned.
" " - The indicated task does not exist.

Comments

This script functionPre-defined run book template in the Automation Engine. One single step only, e.g. Start Windows Service, Copy file,… can be used to retrieve information about the status of an executable object.

This script function even returns a value if the task is no longer active because this information is retrieved from the statisticsThis is a list of a task's previous runs.. An empty string is returned if no statistical records are available.

All the parameters of this script function are optional. If you use only the parameter Request, ensure that two commas are set that replace the non-used parameters.

Example:

:SET  &STATUS# = GET_UC_OBJECT_STATUS( ,,"STATUS")

If object type and RunID are not specified, the status of the task that uses this script function is returned.

If object type or RunID are not specified, the following peculiarities apply:

An empty string is returned if object type and RunID do not comply with each other. An empty string is also returned if no task could be found for the specified RunID.

If Request is not used, the script function returns the status code. 

It is also possible to retrieve the status text for jobs. This is the text that was output by the Job Messenger in the Trailer or was modified with :MODIFY_STATE. Other object types return an empty string.

Examples

The first example activates the jobAn Automation Engine object type for a process that runs on a target system. "DB.USE" so that its status can be retrieved. An additional script function is used to retrieve the job's run number.

:SET &JNR# = ACTIVATE_UC_OBJECT(JOBS,DB.USE)
:
SET &STATUS# = GET_UC_OBJECT_STATUS(JOBS,&JNR#)

:PRINT "The status of the job(&JNR#) is &STATUS#".

The second example retrieves a task's own status. This status is output in the activation protocol.

:SET &RET# = GET_UC_OBJECT_STATUS()
:
PRINT &RET#

In the third example, the script of a job should retrieve 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."]'s (parentThere are different ways of activating objects. The originator of an activation is referred to as the superordinate task (parent). See also: Child; Children) status. Because two different object types are included, the workflow's object type and RunID must be assigned to the script function.

:SET &RUNNR# = SYS_ACT_PARENT_NR()
:
SET &STATUS# = GET_UC_OBJECT_STATUS (JOBP,&RUNNR#)
:
SEND_MSG BU,BU,"The workflow's status is: &STATUS#."

The fourth example returns a job's status text.

:SET &RET# = GET_UC_OBJECT_STATUS(,,"STATUS_TEXT")
:
PRINT &RET#

 

See also:

Script element Description

:MODIFY_STATE

Modifies a return code or status text of a job when it has finished.

Script Elements - Activation Data

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