Skip to main content

TrFile_UnZip (function reference)

Troi File Plug-in for FileMaker Pro

TrFile_UnZip

Expands a ZIP file into the specified folder.

SyntaxFunction badge

TrFile_UnZip ( switches ; sourceZipFileSpec ; destFolderSpec )

Parameters

switches modifies the behavior of the function
sourceZipFileSpec the path to the ZIP file to be unzipped
destFolderSpec the path to the folder where the ZIP is going to be expanded

Switches

You can add one or more of these switches:

-DontCreateArchiveFolder don’t create an extra top folder if there are multiple items at the top level of the ZIP file
-OverwriteExisting overwrite existing items in the destination folder(s)

You can also add one of these encoding switches, which determine how the filenames in the ZIP file bytes are interpreted.

-Encoding=ASCII_DOS
-Encoding=ASCII_Windows (Windows ANSI)
-Encoding=ASCII_Mac (Mac Roman)
-Encoding=ISO_8859_1 (Windows Latin-1)
-Encoding=UTF8

Returned Result

Data type returned

Error code

Result

The returned result is an error code. An error always starts with 2 dollars, followed by the error code. You should always check for errors. Returned error codes can be:

0 no error The ZIP file was unzipped
$$-43 fnfErr Source file not found
$$-48 dupFNErr Destination ZIP folder already exists

Other errors may be returned.

Originated in

Troi File Plug-in 8.5

Compatibility

FileMaker Pro 16 to FileMaker Pro 2023

Considerations

The TrFile_UnZip function will create the complete (sub)folder structure of the ZIP. This may take a bit of time for large ZIP files.

WARNING only use the switch “-OverwriteExisting” when you are sure you don’t overwrite something important. If you first want to see what is in the ZIP file you can use the TrFile_GetZipInfo function to get a list of items. Alternatively it might be better to extract the contents of the ZIP in an empty folder first, and then copy the extracted files from that folder.

Version 13.0 added the -Encoding=xxx switches (on Windows only). The filenames in the ZIP file will be interpreted according to this switch. This is useful if the ZIP was created using a non-standard filename encoding. On macOS the encoding switch is currently ignored.
v13.0 Adds support for the ZIP64 format extension.

Example

Set Field [ $ErrorCode ; TrFile_UnZip ( "-Unused" ; "D:\myZIP2016.zip"; "C:\resultDir\" ) ]

This will uncompress the ZIP file myZIP2016.zip into the folder resultDir. For example these files and folders might be created on the disk:

C:\resultDir\my report\illustration.jpg
C:\resultDir\my report\my report\extra data\
C:\resultDir\my report\my report\extra data\note.txt

Example 2

We assume that in your FileMaker file the following fields are defined and filled with the paths to the source ZIP file and destination folder:

  this::sourceZipPath      	may contain something like "MacHD:Users:kip:bigtext.zip" 
  this::destOfUnZIP_Path	may contain something like "MacHD:Users:destFolder"

This example will first set the variables from the paths stored in the two fields, and then expand the ZIP file. In a script add the following steps:

# Initialize: copy the fields into variables first:
Set Variable [ $SourceZIPfilePath ; this::sourceZipPath ]
Set Variable [ $DestinationFolder ; this::destOfUnZIP_Path ]

# Now unZIP it:
Set Variable [ $ErrorCode ; TrFile_UnZip ( "-OverwriteExisting" ; $SourceZIPfilePath ; $DestinationFolder ) ]

# Return the resulting error code:
Exit Script [ $ErrorCode ]

NOTE: in this example we have specified the switch “-OverwriteExisting”. Only use this switch if you want to allow that existing items in the destination folder can be overwritten.

Used in example file

ZIPAndUnZIP.fmp12

Related functionsFunction badge

TrFile_CreateZip
TrFile_GetZipInfo

Related script stepScript step badge

UnZip

Related topics

Troi File Plug-in online help (overview)


Online Help Page for Troi File Plug-in for 16 to 2023 –> TrFile_UnZip (filep4304) 2023-0601 16:10:35