: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:

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.

Syntax

:MODIFY_STATE Property=Value

Parameters

Example

A Windows job is supposed to copy a file, but the file does not exist. The Job ends normally, with the return code 0. Only in the job report can you see that the file was not found.

The following script in the Post Process page of the Job analyzes the job report. The script recognizes the absence of the file, and changes the return code. As a result, the Job is canceled.

:SET &HND# = PREP_PROCESS_REPORT(,,,"*cannot find the file*")
:
PROCESS &HND#
:  
MODIFY_STATE STATUS_TEXT="Files not found"
:  
MODIFY_STATE RETCODE=50
:
ENDPROCESS

See also:

seealso

Error Handling in Scripts

Notification (CALL)

User Return Codes of Executable Objects

System Return Codes of Executable Objects