Blitz3D+ Command Reference

FilesystemError$ ( )

Parameters

None.

Description

Returns a readable message describing the last recoverable filesystem failure.

The Application Data file commands treat expected failures - a missing save, a locked file, a full disk, a bad path - as recoverable: they return 0 or an empty result instead of stopping the program, and leave the explanation here. FilesystemError gives the human-readable line for your log or "could not save" dialog, naming the operation and the operating-system message.

It heads a family of three set together on every failure:
FilesystemErrorCode: the raw Win32 (or package) error code
FilesystemErrorPath: the path the failed operation was working on

The commands that report here are LoadJson (when reading fails), SaveJsonAtomic, WriteTextAtomic, WriteBankAtomic, CreateDirTree, and Sha256File / Sha256FileBytes. A successful operation from this family clears all three values, so read them straight after the call that failed. Classic filesystem commands (OpenFile, ReadFile and friends) keep their own conventions and do not report here.

The diagnostics are context-local: the main program and each Job worker see only their own failures.

For the full rules, see the Application Data language reference.

Requires Extended mode.

See also: FilesystemErrorCode, FilesystemErrorPath, WriteTextAtomic, SaveJsonAtomic, Sha256File.

Example

; FilesystemError Example
; -----------------------
; Requires Extended mode.

; Try to hash a save file that does not exist - a recoverable
; failure that returns empty and sets the filesystem diagnostics
digest$=Sha256File("missing_save_example.json")
Print "Sha256File returned '"+digest+"' (empty = failed)"
Print ""

; FilesystemError returns a human-readable description of what
; went wrong - ideal for logs and error dialogs
Print "FilesystemError:"
Print "  "+FilesystemError()
Print ""

; Its companions add the raw code and the exact path involved
Print "FilesystemErrorCode: "+FilesystemErrorCode()
Print "FilesystemErrorPath: "+FilesystemErrorPath()

Print ""
Print "Press any key to close the example"
WaitKey

End

Index