GET_UC_OBJECT_STATUS

Use the GET_UC_OBJECT_STATUS script function to retrieve the status of an activated object.

Syntax

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

Parameters

GET_UC_OBJECT_STATUS
Retrieves the status of an activated object
Object Type
(Optional) Short form of the object type
The short forms are displayed in parentheses in this overview: Object Types.
Format: AE name, script literal or script variable
RunID
(Optional) RunID of the activated object
Format: script literal or script variable
Request
(Optional) Specifies the information to retrieve about the activated object
Note: If you do not specify the request, the function returns the status code.
Format: script literal or script variable
Allowed values:
- RETCODE
  Retrieves the return code of the activated object
- STATUS
  Retrieves the current status of the activated object
  For more information, see System Return Codes of Executable Objects.
- STATUS_TEXT
  (Jobs on OS Agents only) Retrieves the status text
  The status text is the text that is printed by the Job Messenger in the Trailer or modified with the :MODIFY_STATE script statement.

All parameters are optional. If you do not specify values for Object Type or RunID, set two commas before the Request parameter.

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

Return Codes

The possible return codes depend on the parameters that you define.

The script function returns the status of the task that the script is in when you define the parameters as follows:

You specify the object type and RunID of the task that contains the script
You omit both the object type and the RunID, or do not specify any parameters
You specify either the RunID of the task that contains the script, or the same object type as the task

To return the status of a different task, specify the RunID of the desired task. If the task is of a different type than the task that contains the script, specify the object type.

The script function returns an empty string in the following situations:

The task that you specified does not exist
The object type and RunID that you specified do not comply with each other
No statistical records are available for the task that you specified
You requested the status text in the parameters, but the task is not a Job

Note: The script function returns a value even if the task is no longer active, because the information is retrieved from the statistics.

Examples

The following example activates a Job (DB.USE). The script retrieves the status of the Job, and prints the status and RunID in the activation report.

: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 following example retrieves the status of the task that contains the script. The script prints the status in the activation report.

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

The following script is in a Job that is a part of a Workflow. The script retrieves the status of the Workflow.The parameters of GET_UC_OBJECT_STATUS specify the object type and RunID of the Workflow because the Job and Workflow are different object types. The script sends a message to a particular user (Jane in the Engineering department) to inform them of the status of the Workflow.

:SET &RUNNR# = SYS_ACT_PARENT_NR()
:SET &STATUS# = GET_UC_OBJECT_STATUS (JOBP,&RUNNR#)
:SEND_MSG JANE,ENGINEERING,"The status of the workflow is &STATUS#."

The following example returns the status text of a Job.

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