Extract()
Previous  Top  Next

:Extract() - Extract a single (File) Entry to Disk.

Syntax

:Extract(<cEntry> | <nEntry> | <oEntry>,  
        [<cTargetRoot>],  
        [<lCreateDirs>],  
        [<lOverwrite>]) --> nError  

Parameters

The first Parameter can be either a Character String, a Number, or a Central Directory Record Object:  
 
<cEntry>  
<cEntry> specifies the File Name of the Central Directory Record Entry that contains the information for the (File) Entry that should be extracted from the Zip File.  

<nEntry>  
<nEntry> specifies the Index Number of the Central Directory Record Entry that contains the information for the (File) Entry that should be extracted from the Zip File.  

<oEntry>  
<oEntry> specifies the ZipCentralDirectoryRecord object of the (File) Entry that should be extracted from the Zip File.  

<cTargetRoot>  
<cTargetRoot> optionally specifies the Target Directory into which the File or Directory should be extracted. The default value is the Current Directory of the Current Drive.  

<lCreateDirs>  
<lCreateDirs> optionally specifies if Directories, which are indicated in either the <cTargetRoot> directory or in a stored Directory Entry of the Zip File, should be created if they do not exist. The default value is .T. (TRUE), which means that unless this parameter is explicitly set to .F. (FALSE), all specified directories will be created.  
 
If this parameter is set to .F. (FALSE), only a (File) Entry that can be extracted into the <cTargetRoot> (which must already exist in this case) will be saved, while stored Directories are not extracted or created -- they will simply be ignored. If <cTargetRoot> does not exist, the (File) Entries is not extracted at all!  

<nOverwrite>  
<nOverwrite> optionally specifies if existing Files should be replaced or not. The default value is "XBZ_OVERWRITE_OLDER", which means that only existing Files that are Older than the Date/Time Stamp of the to-be-extracted (File) Entry are replaced and overwritten, while Files with the same or a newer File Date/Time Stamp are left unchanged. Possible options are the following Define Constants from the XbZLib.ch file:  
 
Define
Value
Description
XBZ_OVERWRITE_NEVER
0
Never overwrite/replace existing Files.
XBZ_OVERWRITE_OLDER
1
Overwrite/replace only Older Files.
XBZ_OVERWRITE_ALL
2
Always overwrite/replace existing Files.
 

Returns

This method returns an Error Code that indicates if the Extracting/Saving of the File was successful or not. Possible values include the following Define Constants from the XbZLib.ch file:  
 
Define
Value
Description
XBZ_OK
0
Extracting/Saving of File was successful.
XBZ_DATA_ERROR
-3
(ZLib Error Code) Corrupted Data/Buffer.
XBZ_MEM_ERROR
-4
(ZLib Error Code) Not enough Memory.
XBZ_BUF_ERROR
-5
(ZLib Error Code) Output Buffer too small.
XBZ_COMP_SHRUNK * (-10)
-10
(Invalid Compression Method) "XBZ_COMP_SHRUNK".
XBZ_COMP_REDUCED1 * (-10)
-20
(Invalid Compression Method) "XBZ_COMP_REDUCED1".
XBZ_COMP_REDUCED2 * (-10)
-30
(Invalid Compression Method) "XBZ_COMP_REDUCED2".
XBZ_COMP_REDUCED3 * (-10)
-40
(Invalid Compression Method) "XBZ_COMP_REDUCED3".
XBZ_COMP_REDUCED4 * (-10)
-50
(Invalid Compression Method) "XBZ_COMP_REDUCED4".
XBZ_COMP_IMPLODED * (-10)
-60
(Invalid Compression Method) "XBZ_COMP_IMPLODED".
XBZ_COMP_TOKENIZED * (-10)
-70
(Invalid Compression Method) "XBZ_COMP_TOKENIZED".
XBZ_COMP_DEFLATE64 * (-10)
-90
(Invalid Compression Method) "XBZ_COMP_DEFLATE64".
XBZ_COMP_PKDCL * (-10)
-100
(Invalid Compression Method) "XBZ_COMP_PKDCL".
ERROR_FILE_NOT_FOUND
2
(OS Error Code) The (File) Entry could not be found in the Zip File.

ERROR_FILE_EXISTS


80
(OS Error Code) A File with the specified File Name already existed at the specified location, and the <nOverwrite> Parameter did not allow the replacing of the existing File, or the existing File could not be deleted/overwritten for some other reason (the File was Open or the Read-Only File Attribute was set, etc.)
 
 
If an incompatible Compression Method is specified -- any method besides "0" (XBZ_COMP_STORE) and "8" (XBZ_COMP_DEFLATED) is incompatible -- the Error Code will be set to the negative of the specified Compression Method Code, multiplied by 10! This means that the above listed nine incompatible Compression Method Error Codes could be generated. The type of the (incompatible) Compression Method can be determined by dividing the given Error Code by (-10), whenever the reported Error Code is less than (-9).  
 
Also possible are all other OS Error Codes that might be created while trying to create a Directory or while trying to create, replace, or write to a File, or while attempting to set/change a File's Date/Time Stamp or File Attributes. OS Error Codes are always greater than "0"!  

Description

Extracts and un-compresses the specified (File) Entry from a Zip File, and saves it in the given <cTargetRoot> directory. If the Entry is a stored Directory, or if the <cTargetRoot> directory does not already exist, all necessary directories will be created, even though this feature can be disabled, in which case Files are created in the <cTargetRoot> directory (which must already exist), while stored Directory Entries are simply ignored.  
 
Existing Files can either be skipped, always overwritten and replaced or only overwritten and replaced if they are older than the Date/Time Stamp of the to-be-extracted (File) Entry. If the (File) Entry is not skipped, the File Attributes and the Date/Time Stamp of the extracted File or Directory are updated as specified in the (File) Entry -- with the exception of the Date/Time Stamp of Directories, which are never changed.  
 
If it wasn't possible to create (or update) the specified Directory or File for any reason, an Error Code other than XBZ_OK will be returned.  
 
NOTE: The supported File Attributes are ONLY valid for MS DOS and Windows (FAT/VFAT/NTFS)!  

Example

Extract the File "MyFile.xxx" from the Zip File "MyArchive.zip", which is opened in Read-Only mode, into the target directory "C:\NewDir\" and also create all necessary directories, including the target directory, if it does not exist. If a File with that File Name already exist, it is overwritten/replaced. Then close the Zip File:  

LOCAL oZip   := XbZLibZip():New('MyArchive.zip', XBZ_OPEN_READ)  
LOCAL nError := oZip:Extract('MyFile.xxx', 'C:\NewDir\', .T., ;  
                             XBZ_OVERWRITE_ALL)  
if nError # XBZ_OK  
   QOut('Error Code: ' + alltrim(str(nError)) + ' was returned!')  
endif  
oZip:Close()