YOUSEFUL / FILEMAKER

YsflFile — Function Reference

FAQ, examples and tutorial

All functions use the YsflFi_ prefix. Parameters in {braces} are optional.

Error Handling

Mutating functions (New, Delete, Copy, Move, Set, Open, Reveal, Run, Compress, Decompress) return:

• 0 on success
• A negative Windows error code on failure

Write instead returns the number of bytes written on success, or a negative error code.

Use YsflFi_Get("lastError") and YsflFi_Get("lastErrorMessage") to retrieve the last error.

YsflFi_Version

Returns plugin version information.

Syntax: YsflFi_Version( {format} )

Returns: Text

YsflFi_New

Creates a new file or folder.

Syntax: YsflFi_New( path {; itemKind} )

Returns: Number (0 = success, negative = error)

Example:

YsflFi_New( "C:\Data\Reports" )                  // creates folder
YsflFi_New( "C:\Data\output.txt" ; "file" )      // creates empty file

YsflFi_Delete

Deletes a file or folder. Folders are deleted recursively.

Syntax: YsflFi_Delete( path )

Returns: Number (0 = success, negative = error)

YsflFi_Copy

Copies a file or folder. Folders are copied recursively.

Syntax: YsflFi_Copy( source ; target )

Returns: Number (0 = success, negative = error)

YsflFi_Move

Moves or renames a file or folder.

Syntax: YsflFi_Move( source ; target )

Returns: Number (0 = success, negative = error)

Notes: Can move across drives (uses copy + delete internally via MOVEFILE_COPY_ALLOWED).

YsflFi_Read

Reads text content from a file.

Syntax: YsflFi_Read( path {; start {; length}} )

Returns: Text (file contents), or "?" on error

Notes:

• Maximum read size is 256 MB per call
• Returns raw bytes as text; binary files will produce garbled output

YsflFi_Write

Writes text data to a file.

Syntax: YsflFi_Write( path ; data {; start} )

Returns: Number (bytes written, or negative error code)

Notes:

• If start is 0 (default), the file is created or overwritten
• If start > 0, the file is opened for appending at that offset
• Maximum write size is 16 MB per call

YsflFi_List

Lists the contents of a directory.

Syntax: YsflFi_List( path {; itemKind} )

Returns: Text — carriage-return-separated list of names (not full paths)

Example:

YsflFi_List( "C:\Data" ; "file" )    // "report.pdf¶invoice.xlsx¶notes.txt"

YsflFi_Get

Gets file metadata or system information.

Syntax: YsflFi_Get( selector {; path} )

Returns: Text or Number depending on selector. Returns "?" if the path is invalid or the selector is unrecognized.

Examples:

YsflFi_Get( "size" ; "C:\Data\report.pdf" )          // 1048576
YsflFi_Get( "modified" ; "C:\Data\report.pdf" )       // "01/15/2026 14:30:00"
YsflFi_Get( "exists" ; "C:\Data\missing.txt" )        // 0
YsflFi_Get( "lastError" )                              // 0

YsflFi_Set

Sets file metadata.

Syntax: YsflFi_Set( selector ; path ; value )

Returns: Number (0 = success, negative = error)

Example:

YsflFi_Set( "modified" ; "C:\Data\report.pdf" ; "06/15/2025 09:00:00" )

YsflFi_Choose

Shows a native Windows file or folder picker dialog.

Syntax: YsflFi_Choose( kind {; prompt {; initialPath {; filter}}} )

Returns: Text — selected path(s), carriage-return-separated for multi-select. Returns "-128" if the user cancels.

Example:

YsflFi_Choose( "file" ; "Select a report" ; "C:\Data" )
YsflFi_Choose( "files" ; "Select images" )
YsflFi_Choose( "new" ; "Save export as" ; "C:\Output" ; "export.csv" )

YsflFi_Open

Opens a file or URL with the default application, or opens a file with a specified application.

Syntax: YsflFi_Open( path {; appPath} )

Returns: Number (0 = success, negative = error)

Examples:

YsflFi_Open( "C:\Data\report.pdf" )                              // default PDF viewer
YsflFi_Open( "C:\Data\report.pdf" ; "C:\Program Files\Acrobat\Acrobat.exe" )

YsflFi_Reveal

Reveals a file or folder in Windows Explorer, with the item selected.

Syntax: YsflFi_Reveal( path )

Returns: Number (0 = success, negative = error)

YsflFi_Run

Runs an executable with optional arguments.

Syntax: YsflFi_Run( path {; args} )

Returns: Number (0 = success, negative = error)

Notes: The process runs detached. The function returns immediately without waiting for it to finish.

Example:

YsflFi_Run( "C:\Tools\converter.exe" ; "--input report.pdf --output report.docx" )

YsflFi_Compress

Creates a ZIP archive from a file or folder.

Syntax: YsflFi_Compress( archivePath ; sourcePath )

Returns: Number (0 = success, negative = error)

Notes: Folders are compressed recursively. Directory structure is preserved within the archive.

Example:

YsflFi_Compress( "C:\Backup\data.zip" ; "C:\Data\Reports" )

YsflFi_Decompress

Extracts a ZIP archive.

Syntax: YsflFi_Decompress( archivePath {; outputDir} )

Returns: Number (0 = success, negative = error)

Example:

YsflFi_Decompress( "C:\Backup\data.zip" ; "C:\Restored" )