:MODIFY_STATE

Use the :MODIFY_STATE script statement to change the return code or status text of a Job after the task has finished.

When you modify the return code, you also modify the status of the Job. The maximum return code for a normal job end, as defined on the Runtime page of the Job, determines what status the Job gets when it has run. If the modified return code is higher than the defined maximum return code, the Job gets ENDED_NOT_OK status. If the modified return code is lower than or equal to the maximum return code, the Job ends with ENDED_OK status.

When you use :MODIFY_STATE to change the status text of a Job, the script replaces the text that the Job Messenger prints in the trailer with the text that you specify.

Important! :MODIFY_STATE is only allowed in the Post Process page of the Job, because the Job must have finished before the script is called.

More Information:

Notes:

Changes are logged in the Post processing (POST) page of the Job report. For more information, see Reports Reports.
The modified values are displayed in the Details of the Job. For more information, see Viewing Object and Task Details.

Tip: Use :MODIFY_STATE to assign the ENDED_NOT_OK status to a Job which has ended normally from a technical point of view, but where an error occurred that is not detected until the job report is analyzed. For more information, see PREP_PROCESS_REPORT and the example below.

Syntax

:MODIFY_STATEProperty=Value

Parameters

:MODIFY_STATE
Modifies the return code or status text of a finished Job
Property
Specifies whether to modify the return code or the status text
Format: AE name or script variable
Allowed values:
- RETCODE
  Return code of the Job
- STATUS_TEXT
  Status text of the Job
- Value
  New value to assign to the property
  Format: script literal, script variable, AE name, number without quotations or script function
  Return code: numerical value
  Status text: alphanumeric string, maximum 32 characters

Example

A Windows Job object is used to edit an existing file. While this Job is being executed, a logical error occurs. Despite this fact, the job ends normally (ENDED_OK) with the system return code 0 which is the default return code if no technical error occurs. To find out if something went wrong during the execution, you need to analyze the Job report, and change the system return code to ENDED_NOT_OK in case something went wrong:

To illustrate this situation, use the following Job Control Language (JCL) in the Process page:

@echo off

echo "#**********************************************************#"

echo "#* the started process produced an error - ReturnCode: 1 *#"

!echo "#* the started process did run successfully *#"

echo "#**********************************************************#"

echo %errorlevel%

@if NOT %ERRORLEVEL% == 0 goto :retcode

The Job ends normally and its report (REP) shows the following information:

c:\M123WS\B\agents\win64\bin\UCXJWX6M.EXE JNR=0007694321 MNR=0100 PNR=2611 IPA=10.49.164.60 TYP=S TXT=" Job started"

Program 'UC4 Job Messenger' version '12.3.3’ started

UCMDJP: *********************************************************************

UCMDJP: ** JOB 0007694321 (ProcID:0000011976) START AT 15.04.2020/16:54:40 **

UCMDJP: ** UTC TIME 15.04.2020/14:54:40 **

UCMDJP: ** --------------------------------------------------------------- **

UCMDJP: ** USED: 0.000 CPU **

UCMDJP: ** 3 PROCESSES **

UCMDJP: ** 6274 PAGE FAULTS **

UCMDJP: *********************************************************************

Program 'UC4 Job Messenger' version '12.3.3' terminated normally

ECHO is off.

"#*********************************************************#"

"#* the started process produced an error - ReturnCode: 1 *#"

"#*********************************************************#"

Program 'UC4 Job Messenger' version '12.3.3' started

UCMDJP: *********************************************************************

UCMDJP: ** JOB 0007694321 (ProcID:0000011976) ENDED AT 15.04.2020/16:54:40 **

UCMDJP: ** UTC TIME 15.04.2020/14:54:40 **

UCMDJP: ** --------------------------------------------------------------- **

UCMDJP: ** USED: 0.000 CPU **

UCMDJP: ** 4 PROCESSES **

UCMDJP: ** 8693 PAGE FAULTS **

UCMDJP: *********************************************************************

Program 'UC4 Job Messenger' version '12.3.3’ terminated normally

To analyze the Job report, use the following script in the Post Process page of the Job:

:SET &HND# = PREP_PROCESS_REPORT(,,,"*error*")
:PROCESS &HND#
: MODIFY_STATE STATUS_TEXT="A logical error occurred"
: MODIFY_STATE RETCODE=1

: FORMAT
:ENDPROCESS

PREP_PROCESS_REPORT analyzes the Job report and recognizes that the word "*error*" is used in it. Therefore, :MODIFY_STATE is used to change the existing return code from 0 to 1 which simulates the corresponding (Windows) OS error code. The Post processing (POST) report shows this information, and the Job aborts.

Tips:

The AE system can generate extended reports which provide additional information about scripts, JCL, and object accesses. Activate the Extended Reports Section in the Job object's General Page for this purpose. For details, see Extended and External Output Reports.
By default, Job reports show the return code with leading zeros. You can remove them to have return codes shown in a more user-friendly way. For details, see FORMAT
Another option to search and set filters in Job reports is to use the External Output Files page of a Job object. For details, see Output Pages