The very first thing you must do (after registering the Unzip functions, if needed), is to open a ZIP archive from which you will extract data. Some of the other Unzip functions need to be told the archive to operate upon, and will raise a REXX SYNTAX condition if you try to call them before opening an archive.

You open a ZIP archive by calling UnzipOpen() once.

The first arg you pass is the name of some REXX variable where you would like UnzipOpen to store a "handle" to the ZIP archive. This handle will need to be passed to other Unzip functions you call.

What you pass for the second arg depends upon the third arg, which is the Option arg. UnzipOpen has the option of opening an existing ZIP archive on your hard drive, or opening the ZIP archive from memory, or spooling the archive from a pipe or already open file. The Option arg tells how you want the archive opened.


An archive on disk

To open an archive on disk, you specify the "FILE" option. In this case, the second arg you pass will be the filename for the archive. For example, here we tell UnzipOpen to open a ZIP archive on disk with the name "MyTest.zip", and return a handle to it in the variable named "MyZipHandle":

/* Open a ZIP archive on disk named "MyTest.zip". */
UnzipOpen("MyZipHandle", "MyTest.zip", "FILE")
Since "FILE" is the default option for UnzipOpen, you can omit the third arg if desired:
UnzipOpen("MyZipHandle", "MyTest.zip")
Above, the file is assumed to be in the current directory. If the archive is located somewhere else, you can pass the full path name. For example, here the archive is in "C:\MyDir":
UnzipOpen("MyZipHandle", "C:\MyDir\MyTest.zip")


An archive in memory

To open an archive in memory, you specify the "MEMORY" option. In this case, the second arg you pass will be the actual contents of the archive. For example, assume that a ZIP archive is contained in the variable "MyArchive". Here we tell UnzipOpen to open that ZIP archive in memory, and return a handle to it in the variable named "MyZipHandle":

/* Open a ZIP archive stored in the variable "MyArchive". */
UnzipOpen("MyZipHandle", MyArchive, "MEMORY")
Note: You must not alter the value of any variable from which the archive is gotten, until after you UnzipClose the handle.


Password encryption

If you wish the contents of the ZIP archive to be decrypted, then you can pass your desired password string as the fourth arg to UnzipOpen. Here we set a password of "My password".

UnzipOpen("MyZipHandle", MyArchive, "MEMORY", "My password")
Note: You can set a password for an archive opened on disk too.


Set the current item

After opening the ZIP archive, you can then extract items from it.

To extract an item (file) from the archive, you must first call UnzipSetCurrentItem() to set that item as the "current item". The first arg is the handle you received from UnzipOpen.

The second arg is the name of a stem variable where you would like information returned about the item.

The third arg is the desired number of the item, where 1 is the first item in the archive, 2 is the second item, etc.

Here we set the first item in the archive as current, and return information in the stem variable "Info":

/* Make the first item current. */
UnzipSetCurrentItem(MyZipHandle, "Info", 1)

/* Display the information about the item. */
SAY "Item's name:" Info.0
SAY "Item's uncompressed size:" Info.1
SAY "Item's compressed size:" Info.2
SAY "Item's attributes:" Info.3
If you know the name of a particular item within the archive, and you wish to make it the current item without knowing its index, then use UnzipFindItem(). The first arg is the handle you received from UnzipOpen.

The second arg is the name of a stem variable where you would like information returned about the item.

The third arg is the name of the item.

The fourth arg is a 1 if you want a case-sensitive match, or 0 otherwise. (Omitting this arg is the same as passing 0). Here we set an item named "Readme.txt" as the current item in the archive:

/* Make the "Readme.txt" item current. */
UnzipFindItem(MyZipHandle, "Info", "Readme.txt")
To determine how many items are in an archive, call UnzipFindItem, passing only the ZipHandle, and the name of a variable:
/* Determine how many items are in the archive. */
UnzipFindItem(MyZipHandle, "Count")
SAY "There are" Count "items."

Extracting the current item to a file

Once you've set the current item, you can then extract it from the archive by calling UnzipGetItem(). The first arg is the handle you received from UnzipOpen.

What you pass for the second arg depends upon the third arg, which is the Option arg. UnzipGetItem has the option of extracting the item to a file on your hard drive, or to a REXX variable, or to a pipe or already open file. The Option arg tells where the item is to be stored.

To specify a file on your hard drive, you pass an option of "FILE". In this case, the second arg is the name of the file. For example, here we extract the current item to a file named "Readme.txt":

/* Extract to a file on disk named "Readme.txt". */
UnzipGetItem(MyZipHandle, "Readme.txt", "FILE")
Since "FILE" is the default option for UnzipGetItem, you can omit the third arg if desired:
UnzipGetItem(MyZipHandle, "Readme.txt")
Above, the file is created in the current directory. If you have a specific place where you wish the file to be extracted, you can pass the full path name. For example, here the file is in "C:\MyDir":
UnzipGetItem(MyZipHandle, "C:\MyDir\Readme.txt")
Note: Normally, you'll use the name returned by UnzipSetCurrentItem. It is fully-qualified, relative to the current directory. But you can call UnzipSetRootDir() to change the root directory to a specific place.


Extracting the current item to a variable

To extract the item to a REXX variable, you pass an option of "MEMORY". In this case, the second arg is the name of the variable. For example, here we extract the current item to a variable named "MyFile":

/* Extract to a file on disk named "Readme.txt". */
UnzipGetItem(MyZipHandle, "MyFile", "MEMORY")

Close an archive

After you're done extracting items from the archive, then you'll call UnzipClose() to close that archive.

Note: RxUnzip automatically closes any archives you have left open if your script ends without doing so itself.


Errata

Note: To avoid any conflicts with the names of REXX variables that RxUnzip sets in your script, you should avoid naming any of your own variables ZipErr or ZipHeading.