24U SimpleFile Plug-In 3.0 Syntax

SFile_Version( { versionFormat } )

Returns version string of the active 24U SimpleFile Plug-In, formatted as requested by the parameter.

Parameters

versionFormatDefines the format of the returned version.

Parameter values for versionFormat

"short"To get just the version number. Default value.
"long"To get the plug-in name followed by its version number
"platform"To get the platform of the code currently running
"autoupdate"To get autoupdate compatible (comparable) version number.

Description

This function is very important and it has the same output format in all 24U Plug-Ins. You should call this function every time you need to check if the plug-in is properly installed to the FileMaker. Even if the plug-in is not registered (or badly registered) this function should work. Calling this function in the startup script of your solution is recommended.

Result

Returns requested version format or platform. If this function returns "?" than the plug-in is not properly installed or FileMaker cannot load and activate it for some reason.

Examples

SFile_Version( "long" )
This will return the plug-in name and its version. In this case it is "24U SimpleFile Plug-In 3.0".

SFile_Version( "platform" )
Returns "Mac OS X" or "Windows" depending on the platform the plug-in is currently running.

SFile_Version( "autoupdate" )
Returns "02030400" for the plug-in version 2.3.4.

SFile_Register ( selector )

Provides special functionality to operate with plugin serial numbers.

Parameter values for selector

SerialNumberRegister given SerialNumber and return an error code.
EmailAddressTries to activate with given email address and return an error code.
"Registration window"Show the "Registration window" and return 0.
"About window"Show the "About window" and return 0.
"Status"Return the actual registration state of the plugin: Demo, Demo expired, Trial, Trial Expired, Registered or Dead.
It may return different values in client solutions and server side scripts, depending on the types of licenses the product is registered with.
"Unregister"Unregister all serial numbers related to the product and return an error code.

Description

Use this function to register or unregister 24U SimpleFile Plug-In, to get information about current registration state, or to invoke GUI providing basic registration information and purchase capabilities.

Result

Returns zero or error code depending on the selector.

Examples

SFile_Register( "SFI25C016-BXMW-VNW7-L8AJ-3KGX-VWG8" )
This function will register the plug-in with client serial number SFI25C016-BXMW-VNW7-L8AJ-3KGX-VWG8 for 16 users.

SFile_Register( "user@mail.com" )
In case you do not have a serial number but you want to try the plug-in out, use the string with your email address as selector.

SFile_Register( "unregister" )
This function will unregister every serial number related to 24U SimpleFile Plug-In.

SFile_Register( "About window" )
Similar to opening FileMaker preferences, navigating to the Plug-Ins tab and double-clicking on 24U SimpleFile Plug-In.

Note: All serial numbers here are only for demonstration purposes. They will not work in the plug-in.

SFile_Choose( itemKind { ; prompt { ; initialPath { ; additionalOptions } } } )

Displays a system dialog for choosing an existing file or folder or a destination for a new file.

Parameters

itemKind The kind of the item(s) you would like the user to choose.
prompt A string containing custom title of the invoked dialog.
initialPath The initial path the dialog will use. To learn more about valid path types in SimpleFile, see: Paths in SimpleFile
additionalOptions Suggested name of a file to be created if itemKind is "new" or
a string specifying allowed extensions the user will be able to choose from if itemKind is "file" or "files". Use '|' character as separator.

Parameter values for itemKind

"file" To choose one existing file.
"folder" To choose one existing folder.
"new" To open system dialog with new file (Save As... dialog).
"files" To choose multiple existing files.
"folders" To choose multiple existing folders (only on Mac OS X).

Description

Use this function to invoke operating system dialog to Open or Save file or folder.

Result

Function returns a value list of native full paths chosen by the user. If user clicks cancel button the function returns -128. In the case of error the function returns negative error code.

Examples

SFile_Choose( "new" )
Function invokes "Save As..." dialog where you can specify the name of the new file or folder.

SFile_Choose ( "file" ; "PROMPT" ; "/Users/Tommy/Desktop" ; "pdf|rtf" )
Function invokes "Open..." dialog with title "PROMPT" at Tommy's Desktop and lets the user open files with extensions "pdf" or "rtf".

SFile_Choose ( "new" ; "PROMPT" ; "/Users/Tommy/Desktop" ; "New.txt" )
Invokes "Save..." dialog with title "PROMPT" at Tommy's Desktop and suggests the user to create a file with name "New.txt".

SFile_New( path { ; itemKind } )

Creates new folder (default) or empty file on the specified path.

Parameters

pathThe path to new file or folder. To see valid path type look go to: Paths in SimpleFile
itemKindSpecifies what can be created. Can be either "folder" (default) or "file".

Description

Use this function to create the new file or folder. If the file / folder already exists error -48 is returned and no new item is created. Using SFile_Choose( "new" ) is recommended to obtain valid path.

Result

Function returns 0 if file or folder was created. Otherwise it returns negative error code.

Examples

SFile_New( "C:\\Users\\me\Documents\\TextFile.txt" ; "file" )
This will create a new text file in Documents folder of the user "me" in Windows Vista or 7.

SFile_New( "/Users/me/Documents/NewFolder" ; "folder" )
This will create a new folder "NewFolder" in Documents folder of user "me" on Mac OS X.

SFile_New( "Log.txt" ; "file" )
This will create a new file named "Log.txt" on the same folder where current active FileMaker solution is.

SFile_Delete( path )

Deletes specified file or folder, recursively if it is not empty.

Parameters

pathThe path to existing file or folder. To see valid path type look go to: Paths in SimpleFile

Description

This function deletes specified existing file or folder. It can be very dangerous if misused - it recursively deletes folders. The function does not follow symbolic links however. It uses operating system functions so the file or folder will be moved to Trash and not deleted irreversibly.

Result

Function returns 0 if the file or folder was deleted. Otherwise it returns negative error code.

Examples

SFile_Delete( "C:\\Users\\me\\Documents\\OldNastyFile.doc" )
The file "OldNastyFile.doc" in path "C:\Users\me\Documents" will be deleted in Windows.

SFile_Delete( "/Users/me/WrongScript.command" )
The script file "WrongScript.command" in path "/Users/me" will be deleted in Mac OS X.

SFile_Delete( "Something" )
The item named "Something" will be deleted. The plug-in tries to find file or folder named "Something" in the same folder as currently running FileMaker solution. If it finds file or folder it will delete it.

SFile_Copy( sourcePath ; targetPath )

Duplicates specified file, or folder including all contents.

Parameters

sourcePathThe path to source file or folder. To see valid path types go to: Paths in SimpleFile
targetpathThe path to destination file or folder

Description

If targetPath specifies an existing folder, source item is copied into the target under the source's original name. If targetPath specifies a non-existing item in an existing folder, the source item is copied under new name specified by the targetPath. Fails if target item already exists (error -48).

Result

Function returns 0 if the item was duplicated. Otherwise it returns negative error code.

Examples

SFile_Copy( "C:\\Users\\me\\Documents\\OldNastyFile.doc" ; "C:\\Users\\you\\Documents\\NewNiceFile.doc" )
Duplicates "OldNastyFile.doc" to the new file "NewNiceFile.doc".

SFile_Copy( "pictures/BigPicture.jpg" ; "/Volumes/ImgVolume" )
The file "BigPicture.jpg" stored in folder "pictures", which is in the same folder as the solution, will be copied into folder "/Volumes/ImgVolume".

SFile_Move( sourcePath ; targetPath )

Moves or renames specified file or folder.

Parameters

sourcePathThe path to source file or folder. To see valid path types go to: Paths in SimpleFile
targetPathThe path to destination file or folder

Description

If targetPath specifies an existing folder, source item is moved into the target under the source's original name. If targetPath specifies a non-existing item in an existing folder, the source item is moved and renamed to a new name specified by the targetPath. Note, that targetPath may be a relative path as well. For more info about this feature and its limitations, see: Paths in SimpleFile. Fails if target item exists (error -48), or if the target item's volume is different from the source item's volume (error -1303). In this case use SFile_Copy( sourcePath ; targetPath ) and SFile_Delete( sourcePath ) instead.

Result

Function returns 0 if the file or folder has been moved. Otherwise it returns negative error code.

Examples

SFile_Move( "FileWithBadName.dat" ; "FileWithGoodName.dat" )
This will rename the file with name "FileWithBadName.dat" to "FileWithGoodName.dat" in the current folder of the solution.

SFile_Move( "C:\\Temp\\game_config_backup.ini" ; "C:\\Game\\SomeGame\\GameConfig.ini" )
Move file "game_config_backup.ini" to the folder "C:\Game\SomeGame\" and rename it to "GameConfig.ini".

SFile_Move( "C:\\Temp\\game_config_backup.ini" ; "D:\\Game\\SomeGame\\GameConfig.ini" )
Will fail with -1303 because source and target volumes (drives) do not match.

SFile_Read( path { ; startIndex { ; maxLength } } { ; encoding } )

Reads file or folder content.

Parameters

pathPath to file in any supported form. To see valid path types go to: Paths in SimpleFile. In case the path points to a folder, the rest of the parameters are ignored.
startIndexSpecifies byte offset in file. The first byte of file is on offset 0. The negative number is counted from the end of the file: -1 is the last byte of the file. The default value is 0.
maxLengthNumber of bytes to read from file. The default value is "all" which means that all bytes to the end of the file will be read.
encodingSpecifies text encoding for text file or file type for binary files. To see all possible encodings see Encodings list.
If the encoding is not specified, the plugin tries to guess the encoding from the files extension. In case the file has unknown extension, SFile_Read returns nothing.

Description

This is a universal reader of files and folders. It can read any file, text or binary and it can list the contents of the folder.

Result

The function returns bytes or characters read from the file. In the case of error the function returns "?" and error code is set. Use SFile_Get( "lastError" ) to obtain error code.

Examples

SFile_Read( "SomeText.txt" )
Read contents of the file "SomeText.txt" in the same folder as the solution. Plug-In uses default values, this means it presumes that: Encoding is default system (Mac-Roman on Mac, CP-1252 on Windows) and file type is Text.

SFile_Read( "SomeText.txt" ; 25 ; 1000 )
Similar to previous example. The plug-in will start reading from 25th byte of file and reads only 1000 bytes.

SFile_Read( "/Library/Preferences/Configuration.conf" ; 42 ; 80 ; "utf-8" )
This command will return the content of the file "Configuration.conf" from folder /Library/Preferences/. Data are from 42nd byte. It reads only 80 bytes and decode the text from utf-8 encoding.

SFile_Read( "file:///Library/Preferences/Configuration.conf" ; -80 ; 80 ; "utf-8" )
Very similar to previous example demonstrating another path type. It reads last 80 bytes in file and decode the text from utf-8 encoding.

SFile_Read( "." )
This command will return carriage-return-separated names of files in the folder the current solution is in.

SFile_Write( path ; data { ; startIndex } { ; encoding } )

Reads file or folder content.

Parameters

pathPath to file in any supported form. To see valid path types go to: Paths in SimpleFile
dataFileMaker field containing data which should be written to file.
startIndexSpecifies byte offset in file. The first byte of file is on offset 0. The negative number is counted from the end of the file: -1 is the "byte" right after the last byte of the file. The default value is 0. All bytes from FileMaker rewrites the content of the file.
encodingSpecifies text encoding for text file or file type for binary files. Default values are listed in the next table. To see all possible encodings go to Encodings list

Default file encoding used in encoding parameter for data.

FileMaker Field TypeWritten file type
Text, Number, Date, Time, TimestampThe contents of the field is written to text file with default operating system encoding.
Container with general fileThe file is written to disk in an unchanged form.
Container with pictureThe picture will be written to file using the same type it is stored inside the container.
Container with soundThe sound file will be written to file using the same type it is stored inside the container.
Container with linkLinked file, if available, will be copied "as is" to the target path.

Description

Use this function to write to existing files or to create the new one. The function is able to write binary data from container but don't use it to convert binary data between formats. If you use SFile_Read to load jpg picture this function cannot convert it to gif for example.

Result

The function returns the number of bytes / characters which were actually written. In the case of error the function returns "?" and error code is set. Use SFile_Get( "lastError" ) to obtain error code.

Examples

SFile_Write( "C:\\Documents\\TextFile.txt" ; "Hello World!" )
This function will create (or rewrite) the file "TextFile.txt" to "C:\Documents" folder and it writes text "Hello World!" into this file using operating system default encoding.

SFile_Write( "notes.txt" ; "Interesting note" )
Writes text "Interesting note" into file "notes.txt" in the same folder as the solution.

SFile_Write( "/var/logs/log.txt" ; "09:31 - Something happened\n" ; -1 ; "utf-8" )
This will append the text "09:31 - Something happened" to the end of the file "log.txt" stored inside "/var/logs" and moves cursor to the next line in file. The text will be written using UTF-8 encoding.

SFile_Write( "picture.jpg" ; pictureContainer ; "image" )
Writes picture from container to file.

SFile_Write( "picture.jpg" ; fmTextField ; "hex-dump" )
Text in the text field must be in the hex-dump form, for example: "FE ED 03 DE AD 42 ...". The plug-in will process each hex number (two characters [0-9,A-F,a-f]) into binary file. All non-hex characters (white spaces, newlines etc...) are ignored.

SFile_Write( $path ; $content & char(13) & char(10) )
This function will write contents of variable $content followed by proper Windows new line sequence (CR+LF) to the file located at $path. Most of the Mac appliations should work with it too, but using only LF character (char(10)) is recommended on Mac and Linux.

SFile_Convert( sourcePath ; targetPath { ; name ; value } { ; name ; value } ... )

Converts various file formats and change its internal attributes.

Parameters

sourcePathThe path to source file. To see valid path types go to: Paths in SimpleFile
targetPathThe path to destination file.
nameThe name of the parameter to be altered. Available options depend on the file type.
valueDesired new value of the specified parameter.

Supported parameter names for file types.

File TypeParameterDescription
Picture"width"Function will change width of the picture.
Picture"height"Function will change height of the picture.
Picture"proportional"1 (default) to maintain aspect ratio when resizing picture, 0 to stretch. When both width and height are specified and propotional scaling is on, picture will be fitted to the rectangle specified by width and height.
Picture"exif-rotate"The destination picture will be hard rotated to direction specified in exif data of the source picture. If the source has no exif data, this parameter will be ignored.

Description

The file on sourcePath is read and recognized automatically. Plug-in version 2.0 supports only conversions listed above. More conversion can be added in the future version. If no conversion is necessary the file will be simply copied as is.

Result

The function returns 0 if if the conversion / copy has been successful. In the case of error the function returns non zero status code.

Examples

SFile_Convert( "bigPicture.jpg" ; "thumbnail.jpg" ; "height" ; 24 )
The "bigPicture.jpg" will be converted and saved to "thumbnail.jpg". The picture height will be changed to 24 pixels preserving aspect ratio.

SFile_Convert( "photograph.jpg" ; "thumbnail.jpg" ; "exif-rotate" ; 1 ; "width" ; 24 )
The "photograph.jpg" will be converted and saved to "thumbnail.jpg". The picture will be rotated according to exif meta data and than it will be resized so its width will be 24 pixels preserving aspect ratio.

SFile_Convert( "original.png" ; "deformed.png" ; "proportional" ; 0 ; "width" ; 120 ; "height" ; 120 )
The "original.png" will be resized to 120x120 pixels and saved to "deformed.png". Aspect ratio is not preserved.

SFile_Convert( "original.png" ; "not_deformed.png" ; "proportional" ; 1 ; "width" ; 120 ; "height" ; 120 )
The "original.png" will be resized to fit bounding box 120x120 pixels and saved to "not_deformed.png". Aspect ratio is preserved.

SFile_Open( path { ; pathToApplication } )

Opens the file or folder using either the default application specified by operating system or by the application specified by the user.

Parameters

pathThe path to file or folder which should be opened. See Paths in SimpleFile for the list of valid path types.
pathToApplicationThe path to the application the file (or folder) should be opened with. See Paths in SimpleFile for the list of valid path types.

Description

Launches default application to open the file or folder on the path. Folders are opened in OS default File Manager.

Result

The function returns 0 if the file or folder has been successfully opened. In the case of error the function returns non zero status code.

Examples

SFile_Open( "picture.jpg" )
The picture.jpg should be placed in the same folder as the current active FileMaker solution. On Mac OS X this will probably call Preview.app which will show the file picture.jpg. On Windows the default picture viewer will be opened with the file.

SFile_Open( "picture.jpg" ; "/Applications/Safari.app" )
On Mac OS X this will call Safari.app which will show the file picture.jpg.

SFile_Open( "picture.jpg" ; "C:\\Program Files\\Internet Explorer\\iexplore.exe" )
On Windows this will call Internet Explorer which will show the file picture.jpg.

SFile_Open( "." )
The dot points to current folder so current folder will be opened with the default file manager of the operating system (Finder on Mac OS X and Explorer on Windows).

SFile_Reveal( path )

Opens the file's containing folder and selects it.

Parameters

pathThe path to file or folder which should be opened. See Paths in SimpleFile for the list of valid path types.

Description

Opens file's containing folder in OS default file manager and selects the file.

Result

The function returns 0 if the folder has been successfully opened. In the case of error the function returns non zero status code.

Examples

SFile_Reveal( "~/Documents/file.pages" )
On Mac OS X, the function will open Documents folder and highlights file.pages (if it exists).

SFile_Reveal( "C:\\Documents and Settings\\Public\\Pictures" )
On Windows, the function will open Public folder and highlights Pictures folder (if it exists).

SFile_Run( path { ; arguments } )

Runs the application with given arguments.

Parameters

pathThe path to the application which should be opened. See Paths in SimpleFile for the list of valid path types.
argumentsUnescaped arguments delimited by carriage return which should be passed to the application. For example: "first argument¶second argument¶third argument".

Description

Runs the application with given arguments similar to running the application directly from the command line.

Result

The function returns 0 if the application described by path exists and was executed. In case of an error the function returns non-zero status code.

Examples

SFile_Run("/Applications/iTunes.app" ; "Users/admin/Music/Favorite music.mp3")
On Mac, if iTunes is not opened and the file exist, it will play the file in iTunes. Note, that there is no need to escape the space in the argument list.

SFile_Run( "C:\\Program Files\\Internet Explorer\\iexplore.exe" ; "-extoff¶-private¶ http://24usoftware.com" )
On Windows, it will open 24U software webpage in Internet Explorer in private mode with extensions turned off.

SFile_Mount( URL { ; mountDirPath} { ; username ; password } )

Mounts network volume to specified mount point in file system.

Parameters

URLURL of the network volume. Use format default for each operating system. The plug-in is able to translate OS specific identifiers for Samba volumes: "smb://host" and "\\host" are interchangeable.
mountDirPathThe path to the folder where the user has right to mount network drive. When not specified, "/Volumes/" folder is used on Mac OS X and first available drive letter on Windows.
Note: The mounted volume may not appear on the user's desktop when non-default mount path is used.
See Paths in SimpleFile for the list of valid path types.
usernameOptional username. The default username is the username under which FileMaker Pro runs.
passwordOptional password. The default password is the password of user under which FileMaker Pro runs.

Description

This command will use OS capabilities to mount network volume to the file system. The user must have permissions to mount to specific mountDirPath.

Result

The function returns the full path to the newly mounted network disk. In the case of error the function returns "?" and error code is stored. Use SFile_Get( "lastError" ) to obtain the error code.

Examples

SFile_Mount( "\\fileserver.com\share" ; "Share" )
The plug-in will attempt to mount network volume "share" on host "fileserver.com" to the folder "Share" which must exist in the same folder as the active FileMaker solution. It uses current system username and password.

SFile_Mount( "smb://fileserver.com/share" ; "Share" )
This command does the same as previous command. Both commands work the same on both platforms, Mac OS X and Windows. The plug-in internally translates URL types to be compatible with underlying OS.

SFile_Mount( "http://fileserver.com/share" ; "Share" )
Attempts to mount WebDAV volume to the file system. This command will probably work only on Mac OS X. On Windows the plug-in tries to mount the drive and if Windows fails it returns error -35 (No such volume)

SFile_Mount( "smb://fileserver.com/share" ; "Login" ; "Password" )
The plug-in will attempt to mount network volume "share" on host "fileserver.com" using "Login" and "Password" as login and password.

SFile_Unmount( mountPath )

Unmounts mounted volume from the filesystem.

Parameters

mountPathThe path to the mounted folder. See Paths in SimpleFile for the list of valid path types.

Description

This command will use OS capabilities to unmount volume from the file system. The user must have permissions to unmount the specific mountPath.

Result

The function returns 0 if the volume has been successfully unmounted or non-zero error code in the case of failure.

Examples

SFile_Unmount( "Share" )
This will unmount mounted volume "Share" in the same folder as current active FileMaker solution.

SFile_Unmount( "/Volumes/NetworkDrive" )
This will unmount mounted volume on absolute path "/Volumes/NetworkDrive" on Mac OS X. On Windows it tries to unmount folder "C:\Volumes\NetworkDrive" and if it does not find such folder it returns error -43.

SFile_Unmount( "N:" )
This will unmount mounted volume "N:" on Windows. On Mac OS X it tries to unmount folder named "/Volumes/N". It returns -43 if no such folder exists.

SFile_Get( selector { ; path } { ; parameter } )

Gets important internal parameters of the plug-in and information about storage system.

Parameters

selectorThe name of the parameter which should be get.
pathThe path to file in supported form. See Paths in SimpleFile for the list of valid path types.

Parameter values for selector

selectorDescription
"lastError"Returns the status code of the last performed plug-in function.
"lastErrorMessage"Returns description of the last error generated by the plug-in.
"type"The Parameter should be FileMaker container. Returns type of the contents of FileMaker container. See List of recognized container types below.
"kind"Returns "file" if the path specifies an existing file "folder" if the path specifies an existing folder. Symbolic links are considered as files and Mac OS X volumes as folders. Returns error if the object does not exist.
"created"Returns item's creation date & time as timestamp.
"modified"Returns item's modification date & time as timestamp.
"size"Returns item's total size in bytes. For folder it sums up all file sizes in the folder and subfolders.
"data-size"Returns item's data fork size in bytes. The same as "size" on Windows. For folder it sums up all file data sizes in the folder and subfolders.
"resource-size"Returns item's resource fork size in bytes. Returns 0 on Windows. For folder it sums up all file resource sizes in the directory and subfolders.
"available-space"Returns available space in bytes on the volume where path points to.
"owner"Returns item's owner.
"group"Returns item's group.
"owner-rights"Returns item's owner access rights.
"group-rights"Returns item's group access rights.
"everyone-rights"Returns item's access rights.
pathTypeConverts path from one type to another. See below for the list of supported path types.
pathTypeDescription
"fsspec"Returns Macintosh fsspec. This is unique file or folder identifier used in old Mac OS. Today it is obsolete and it will not work with 64-bit binaries. The format is: "fsspec:VolumeID:FolderID:FileName". On Windows the FileName contains full path to the file and VolumeID and FolderID are 0.
"native-relative"Relative path in the form native to the system. The same as "win-relative" on Windows and "unix-relative" on Mac OS X.
"native-full"Full path in the form native to the system. The same as "win-full" on Windows and "unix-full" on Mac OS X.
"win-relative"Relative path in the form native to Windows. The backslash is used as a separator.
"win-full"Full path in the form native to Windows. Unix paths are converted by changing slashes to backslashes and by adding "C:" before the path.
"unix-relative"Relative path in the form native to Unix. The slash is used as a separator.
"unix-full"Full path in the form native to Unix. To convert Windows path, volume identifier is removed, backslashes changed to slashes.
"FileMaker"Full local path in the form native to FileMaker Pro.
"URL"Full local path in the URL form. The plug-in tries to conform to conventions of underlying operating system.

Description

Use this function to get important parameters of files, folders and system settings.

Result

The function returns actual value of the parameter. In the case of error the function returns "?" and error code is set. Use SFile_Get( "lastError" ) to obtain error code.

Examples

SFile_Get( "created" ; "C:\\Windows" )
Returns the date and time when the Windows folder was created (probably the time when Windows was installed).

SFile_Get( "available-space" ; "D:\\" )
Returns the number of free bytes available on disk D: on Windows.

SFile_Get( "owner-rights" ; "/Users/me/Documents/myDocument.pages" )
Returns "read|write|delete" if you are owner of this bundle / file.

SFile_Get( "type" ; pictureContainer )
Returns "PNGf" if the container has a picture which has been initially loaded from png picture file.

SFile_Get( "FileMaker" ; "/Users/Pete/file.txt" )
Returns "file:/Macintosh HD/Users/Pete/file.txt" on Mac OS X if the system disk is named "Macintosh HD". On Windows it returns "file:/C:/Users/Pete/file.txt" if system disk is C:.

SFile_Get( "FileMaker" ; "C:\\Users\\Pete\\file.txt" )
Returns "file:/Macintosh HD/Users/Pete/file.txt" on Mac OS X if the system disk is named "Macintosh HD". On Windows it returns "file:/C:/Users/Pete/file.txt".

SFile_Get( "native-full" ; "/Users/Pete/file.txt" )
Returns "/Users/Pete/file.txt" on Mac OS X. On Windows it returns "C:\Users\Pete\file.txt".

SFile_Get( "native-full" ; "C:\\Users\\Pete\\file.txt" )
Returns "/Users/Pete/file.txt" on Mac OS X. On Windows it returns "C:\Users\Pete\file.txt".

SFile_Get( "win-full" ; "/Users/Pete/file.txt" )
Returns "C:\Users\Pete\file.txt" on both platforms.

SFile_Get( "URL" ; "/Users/Pete/file.txt" )
Returns "file:///Users/Pete/file.txt" on both platforms.

SFile_Get( "URL" ; "C:\\Users\\Pete\\file.txt" )
Returns "file:///Users/Pete/file.txt" on Mac OS X. On Windows it returns "file://C:/Users/Pete/file.txt"

SFile_Get( "native-full" ; "file.txt" )
Suppose the current active solution in FileMaker is placed in folder "/Users/Pete" on Mac OS X or "C:\Users\Pete" on Windows. The functions returns "/Users/Pete/file.txt" on Mac OS X. On Windows the returned value is "C:\Users\Pete\file.txt".

SFile_Get( "unix-full" ; "file.txt" )
Suppose the current active solution in FileMaker is placed in folder "/Users/Pete" on Mac OS X or "C:\Users\Pete" on Windows. The functions returns "/Users/Pete/file.txt" on both platforms.

SFile_Get( "native-full" ; "../Suzan/file.txt" )
Suppose the current active solution in FileMaker is placed in folder "/Users/Pete" on Mac OS X or "C:\Users\Pete" on Windows. The functions returns "/Users/Suzan/file.txt" on Mac OS X. On Windows the returned value is "C:\Users\Suzan\file.txt".

SFile_Set( selector ; path ; newValue )

Sets important internal parameters of the plug-in and information about storage system.

Parameters

selectorWhich data should be set.
pathThe file or folder which parameters should be changed. See Paths in SimpleFile for the list of valid path types.
newValueThe new value of the parameter.

Parameter values for selector

selectorDescription
"created"Sets the file creation date and time. Use FileMaker timestamp stored in newValue parameter.
"modified"Sets the file modification date and time. Use FileMaker timestamp stored in newValue parameter.
"owner"Sets the file owner. You must have the permission to change owner.
"group"Sets the file group. You must have the permission to change group.
"owner-rights"Sets the file permissions for owner. You must have the permission to change permissions.
"group-rights"Sets the file permissions for group. You must have the permission to change permissions.
"everyone-rights"Sets the file permissions for everyone. You must have the permission to change permissions.

Description

Use this function to set important parameters.

Result

The function returns actual value of the parameter. In the case of error the function returns "?" and error code is set. Use SFile_Get( "lastError" ) to obtain error code.

Examples

SFile_Set( "owner" ; "/Users/me/Documents/someFile.txt" ; "me" )
Changes file owner of the file on path "/Users/me/Documents/someFile.txt" to "me".

SFile_Set( "everyone-rights" ; "C:\\Documents and Settings\\me\\Documents\\someFile.txt" ; "read|write|delete" )
Everyone can read file, write to file and delete file "someFile.txt".

SFile_Compress( archivePath ; sourcePath )

Zip the source file or folder to target archive file.

Parameters

archivePathName of the target zip file to store the compressed data. The path should contain the extension .zip.
sourcePathThe path to the file or folder you want to compress.

Description

Use this function to compress a file or folder.

Result

The function returns 0. In the case of error the function sets error code. Use SFile_Get( "lastError" ) to obtain error code.

Examples

SFile_Compress( "Test/archive.zip" ; "Users/me/Documents/file.txt" )
Compresses the file /Users/me/Documents/file.txt into Test/archive.zip.

SFile_Compress( "Test/archive.zip" ; "Users/me/Documents/folder" )
Compresses the content of /Users/me/Documents/folder into Test/archive.zip recursively.

SFile_Decompress( path { ; targetDirectory } )

Unzip the source archive file to target folder.

Parameters

pathWhich archive should be decompressed.
targetDirectoryName of the folder to store the unzipped content of source archive. The parent folders of the output folder must exist.

Description

Use this function to decompress an archive.

Result

The function returns 0. In the case of error the function sets error code. Use SFile_Get( "lastError" ) to obtain error code.

Examples

SFile_Decompress( "Users/me/Documents/archive.zip" ; "Users/me/Documents/output" )
Decompresses /Users/me/Documents/archive.zip recursively and puts the content into /Users/me/Documents/output.

Paths in SimpleFile

SimpleFile accepts and converts many path types. Here are some examples of paths:

Path ExampleDescription
"C:\folder\file.ext"The Windows full path. Use this type on Windows when you want to specify the exact file or folder position. On Mac OS X SimpleFile tries to convert path to this form: "/folder/file.ext".
"/folder/file.ext"Standard unix full path. Use this type on Mac OS X to specify exact file or folder position. On Windows SimpleFile tries to convert the path to the form: "C:\folder\file.ext".
"folder\file.ext"
"folder/file.ext"
The Windows or Mac relative path respectively. Use this type to specify path to file or folder relative to position of the active solution if the script runs on client. In server side scripts, CWP and IWP they are relative to Get(FileMakerPath). In WebDirect, relative paths are not supported.
On Mac OS X SimpleFile tries to convert this form to the Unix one: "folder/file.ext".
On Windows SimpleFile tries to convert this form to the Windows one: "folder\file.ext".
"file:/volume/folder/file.ext"This is the FileMaker path format. This format can be used in both platforms and it is converted to native full path.
"file:///path/to/file.ext"URL used on unix. 24U SimpleFile Plug-In can read local files using URL. Use the same format as in your internet browser for local files.
"fsspec:-100:883688:file.ext"The old Macintosh FSSpec. This format is obsolete. It has been used in old Mac OS prior to Mac OS X. If you try to use this on Windows SimpleFile will take the only the last part and tries to use it as relative or absolute path.

Paths to directories

Paths to directories have the same form as paths to files. Paths to directories are not ended by slash or backslash except paths in FileMaker format which end with slash.

File Permissions in SimpleFile

24U SimpleFile Plug-In is a part of FileMaker Pro (client side) or FileMaker Server (server side) or Web Publishing Engine (server side) process. All credentials granted to these processes are also valid for the plug-in.

In FileMaker Server on Mac OS X the folder /Library/FileMaker Server/Data is accessible by the plug-in. You can specify more files and folder by adding them to fmsadmin group.

In FileMaker Server on Windows the folder C:\Program Files\FileMaker\FileMaker Server\Data is accessible by the plug-in. You can specify more files and folder by adding them to fmsadmin group.

Valid Encodings

This is the list of valid encodings.

whatDescription
"default",
"text"
The system default encoding for text files. On english system it is "x-mac-roman" on Mac and "windows-1252" on Windows.
"hex-dump"Useful for reading binary files. The content is returned in hex numbers delimited by space.
"base64"Useful for reading binary files. The content is returned in ASCII characters.
"utf-16"Text files encoded in 16-bit encoding.
"utf-8"Utf-8 unicode encoding. The number of bytes is not equal to number of characters.
"x-mac-roman",
"x-mac-arabic",
"x-mac-centraleurroman",
"x-mac-chinesesimp",
"x-mac-chinesetrad",
"x-mac-cyrillic",
"x-mac-greek",
"x-mac-hebrew",
"x-mac-japanese",
"x-mac-korean",
"x-mac-turkish"
Macintosh 8-bit encodings. The first is the most used.
"dos",
"windows-1252",
"windows-1250",
"windows-1251",
"windows-1253",
"windows-1254",
"windows-1255",
"windows-1256",
"windows-1257"
Windows 8-bit encodings. Windows-1252 is used in the English version of Windows..
"iso-8859-15",
"iso-8859-2",
"iso-8859-3",
"iso-8859-4",
"iso-8859-5",
"iso-8859-6",
"iso-8859-7",
"iso-8859-8",
"iso-8859-9"
The encodings defined by the ISO standard.
"euc-jp",
"euc-kr",
"gb2312",
"johab"
The other text encodings.
"image"The image type. The result of the function will be the FileMaker container filled with image.
"jpeg"The jpeg image type. The result of the function will be the FileMaker container filled with jpeg image.
"gif"The gif image type. The result of the function will be the FileMaker container filled with gif image.
"png"The png image type. The result of the function will be the FileMaker container filled with png image.
"bmp"The bmp image type. The result of the function will be the FileMaker container filled with bmp image.
"x-pict"The Macintosh picture type. The result of the function will be the FileMaker container filled with Macintosh picture. FileMaker is able to show Macintosh picture in the container only on Mac.
"file"The general file type. The result of the function will be the FileMaker container with the file icon.
"rtf"The rich text format. Use this format to write styled FileMaker text into rtf file.

Recognized FileMaker Container Types

This is the list of recognized FileMaker Container types.

TypeDescription
"FILE"Generic file with unknown type
"JPEG"JPEG Picture
"PNGf"PNG Picture
"GIFf"GIF Picture
"BMPf"BMP Picture
"PICT"PICT Picture
"TIFF"TIFF Picture

Other container types may be returned if they are natively supported by your version of FileMaker Pro and your operating system, but correct recognition of them by this function is not guaranteed.

Error Codes Table

Here is the list of all error codes which can be returned from the plug-in. The error codes are derived from MacErrors.h header file from Mac OS. Plug-In's custom error codes are positive numbers in range between 2400 and 9999. If function fails it either returns "?" signaling error or it directly returns the error code. If it returns "?" you can use SFile_Get( "lastError" ) to obtain the code.

CodeDescription
-4Not implementedIf you see this error please report the error and steps to reproduce it to 24U Support. This error should never be invoked in the release version of the plug-in.
-33Directory fullNo new file or directory can be added to the directory because file system limits number of nodes. This is a very rare error in modern file systems (HFS+ or NTFS). It can be seen on old flash drives with FAT16 filesystem.
-34Disk fullNo new file or directory can be added to the disk because it is full. Make some space on the disk and try again.
-35No such volumeYou are trying to access volume which doesn't exist.
-36IO foundSomething bad and undefined happened during IO operation. Try it again and if it doesn't help check your file system.
-43File not foundThe function needs existing file or folder but it is not able to find it.
-45File is lockedThe function needs to access the file which is locked.
-47File is busyThe function cannot delete the file which is opened. Check other applications opened files.
-48Duplicate filenameYou are trying to rename the file to the name of some existing file. Choose another name or rename the existing file.
-50Parameter errorOne or more parameters of the function are not in correct format. Function needs more / less parameters. Syntax of the function is wrong.
-52File position errorRead / Write function cannot access this position in the file.
-53Volume on line errorThe volume has been ejected and plug-in cannot access it.
-54Permission errorThe plug-in has permission problem accessing the file.
-1303Different volumeCannot move files or folders between different volumes. Use copy command instead.
2400Unknown errorAn unknown error occurred. If you see this error please report the error and steps to reproduce it to 24U Support. We will try to identify error conditions and add the new error code to this list.
24001Demo mode expired.If you want to keep using the plug-in, you must register it or buy it for particular environment.
24002Product expired.Trial period is over. If you want to keep using the product, you must buy it for particular environment.
24003SN limit was met.The serial number is already registered on too many computers.
24004Product is dead.The product expired and cannot be used any more. Please download the new version from 24U Software.
24005Invalid serial number.Serial number you entered is not valid.
24006Activation failed.Activation failed probably due to some network error. Please, check your connection to the internet and try again later.
24007Deactivation failed.Deactivation failed probably due to some network error. Please, check your connection to the internet and try again later.
24008Unknown serial number.The given serial number cannot be used for the current product. It has been stored so that other product can try to use it.
24009Blacklisted serial number.The given serial number has been blacklisted and cannot be used anymore. Please, contact 24U Support if you need more information.
24010eSellerate engine not installed.This product uses eSellerate to validate user registration and purchases, but its installation failed. Please, reboot the computer or try again later.