| job - a Job handle returned by StartJob |
|
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. A program you run from the IDE names the file by its full path. An executable names it instead by its place beneath the program's folder, such as lib/loader.bb, and an application bundle or a web site by its place among the files it carries, or by its file name alone when the file is outside them. A program you share therefore does not reveal where it was built. A precompiled module object (.b3m) names its module's files by their places beneath the module's folder, wherever you run or build the program that uses it. 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. |
; 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