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

GET_UC_OBJECT_STATUS

Script Function: Returns the status of an activated object.

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 type is clearly identified through its RunID (compatible with Version 2.6xx).

RunID

Run number of the activated object.
Format: script literal or script variable

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 code, status or the status text of the task is returned.
" " - The indicated task does not exist.

Comments

This script function 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 statistics. 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 job "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 workflow's (parent) 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