Blitz3D+ Command Reference

JobErrorFile$ ( job )

Parameters

job - a Job handle returned by StartJob

Description

Returns the source file retained for a failed job, or an empty string.

Together with JobErrorLine and JobErrorFunction, this pins a worker failure to a place in your code - the file containing the Worker Function code that was executing when the error was raised. Since worker errors never open the GUI debugger from the background thread, these retained positions are your debugger: log "JobError at JobErrorFile:JobErrorLine in JobErrorFunction" and you can go straight to the spot.

It returns meaningful text only while JobState is JOB_FAILED; for every other state it returns an empty string.

For the full story, see the Using Background Jobs guide.

Requires Extended mode.

See also: JobError, JobErrorLine, JobErrorFunction, JobState.

Example

; JobErrorFile Example
; --------------------
; Requires Extended mode.

Graphics 640,480,0,2
SetBuffer BackBuffer()

; This worker fails on purpose while loading a corrupted save file
Worker Function LoadCorruptSave(inputBank)
    SetJobProgress 1L,2L,"Verifying checksum"
    ; Busy work standing in for real parsing
    For parse=1 To 4000000
        noise#=Sin(parse)
    Next
    ; The checksum does not match - fail the Job deliberately
    RuntimeError "Save file checksum mismatch"
    Return CreateBank()
End Function

job=StartJob(LoadCorruptSave)

While Not KeyDown(1)

    Cls

    Text 0,0,"Esc: exit"
    Text 70,160,"Loading save file on a worker thread..."

    If JobState(job)=JOB_FAILED
        ; JobErrorFile reports which source file the failed worker was in
        Text 70,210,"JobErrorFile(job) = "+Chr(34)+JobErrorFile(job)+Chr(34)
        Text 70,240,"JobError(job) = "+Chr(34)+JobError(job)+Chr(34)
        Text 70,270,"File, line, and function are retained for failed Jobs only"
    Else
        Text 70,210,"Still loading..."
    EndIf

    Flip

Wend

FreeJob job
End

Index