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.

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:

If object type is the only specified parameter, the status of the own task is returned. Object type and the task's object type must be the same in this case.
If RunID is the only specified parameter, either the status of the own task or the status of a different task can be retrieved.
If the RunID of a different task is assigned to this script function, both tasks must be of the same object type. Otherwise, the object type of the other task must explicitly be specified.

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#