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

• Runtime Page
• Attributes for All Job Types
• Task Status
• Process Pages

Notes:

• Changes are logged in the Post processing (POST) page of the Job report. For more information, see 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.

Syntax

:MODIFY_STATE Property=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 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: