You create a ZIP archive by calling ZipCreate() once.
The first arg you pass is the name of some REXX variable where you would like ZipCreate to store a "handle" to the ZIP archive. This handle will need to be passed to other Zip functions you call.
What you pass for the second arg depends upon the third arg, which is the Option arg. ZipCreate has the option of creating the ZIP archive as a file on your hard drive, or creating the ZIP archive in memory (and leaving you with the responsibility of whether that archive eventually gets stored somewhere, and how), or spooling the archive to a pipe or already open file. The Option arg tells how you want the archive created.
An archive on disk
To create 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 ZipCreate to create a ZIP archive on disk with the name "MyTest.zip", and return a handle to it in the variable named "MyZipHandle":
/* Create a ZIP archive on disk named "MyTest.zip". */ ZipCreate("MyZipHandle", "MyTest.zip", "FILE")Since "FILE" is the default option for ZipCreate, you can omit the third arg if desired:
ZipCreate("MyZipHandle", "MyTest.zip")Above, the file is created in the current directory. If you have a specific place where you wish it created, you can pass the full path name. For example, here we create it in "C:\MyDir":
ZipCreate("MyZipHandle", "C:\MyDir\MyTest.zip")
An archive in memory
To create an archive in memory, you specify the "MEMORY" option. In this case, the second arg you pass will be the maximum size (in bytes) for the archive. For example, here we tell ZipCreate to create a ZIP archive in memory, letting it grow to a maximum of 500000, and return a handle to it in the variable named "MyZipHandle":
/* Create a ZIP archive in memory with maximum size of 500000. */ ZipCreate("MyZipHandle", 500000, "MEMORY")The memory will be allocated only as needed, so you can specify a large maximum size, as above.
Password encryption
If you wish the contents of the ZIP archive to be encrypted, then you can pass your desired password string as the fourth arg to ZipCreate. Here we set a password of "My password".
ZipCreate("MyZipHandle", 500000, "MEMORY", "My password")Note: You can set a password for an archive created on disk too.
Adding entries to an archive
After creating the ZIP archive, you can then add entries to it.
To add (compress) a file to the archive, you call ZipAdd(). The first arg is the handle you received from ZipCreate.
What you pass for the second arg depends upon the third arg, which is the Option arg. ZipAdd has the option of adding a file on your hard drive to the archive, or adding the contents of a variable (or directly passing a string to add as its own entry), or adding the contents of a pipe or already open file. The Option arg tells where the entry's data is coming from.
To specify a file on your hard drive to add to the archive, you pass an option of "FILE". In this case, the second arg is the name of the file. For example, here we add the file named "Readme.txt":
/* Add the file on disk named "Readme.txt". */ ZipAdd(MyZipHandle, "Readme.txt", "FILE")Since "FILE" is the default option for ZipAdd, you can omit the third arg if desired:
ZipAdd(MyZipHandle, "Readme.txt")Above, the file is found in the current directory. If you have a specific place where the file is found, you can pass the full path name. For example, here the file is in "C:\MyDir":
ZipAdd(MyZipHandle, "C:\MyDir\Readme.txt")By default, when the file is added to the archive, the name stored for it is the same as the original name. If you wish a different name for the stored entry, then you can pass the desired name as the fourth arg. Here we give it the name "blort.txt":
/* Add the file on disk named "Readme.txt". */ ZipAdd(MyZipHandle, "C:\MyDir\Readme.txt", "FILE", "blort.txt" )To add the contents of some variable to the archive, you pass an option of "MEMORY". In this case, the second arg is the data to add. You must also pass the desired name for the entry (as the fourth arg). For example, here we add the contents of a variable named "MyVariable", and give the new entry the name "Readme.txt":
/* Add the contents of MyVariable as "Readme.txt". */ MyVariable = "This is some data." ZipAdd(MyZipHandle, MyVariable, "MEMORY", "Readme.txt" )You can also pass a string directly to ZipAdd:
/* Add the string of "This is some data." as "Readme.txt". */ ZipAdd(MyZipHandle, "This is some data.", "MEMORY", "Readme.txt" )You can call ZipAdd as many times as you like, to add as numerous entries to the archive. You can mix and match types of entries. For example, you can call ZipAdd to add a file on disk, and then call ZipAdd to add the contents of some variable.
Storing a memory archive in a variable
After you're done adding entries to an archive in memory, and no longer wish to add any more, then you'll call ZipGetMemory() to store that archive into some variable of your choice.
Note: ZipGetMemory will not store a disk archive in a variable. (Use CHARIN instead). It works only for a MEMORY archive.
For example, here we store the archive in the variable named "MyArchive":
/* Store the archive in "MyArchive". */ ZipGetMemory(MyZipHandle, "MyArchive")You can store a particular archive only once. After ZipGetMemory returns, the memory buffer is reset to empty, in preparation of creating another MEMORY archive by calling ZipAdd to add entries to it, and eventually following up with another ZipGetMemory to store it into a variable.
Close an archive
After you're done with the archive, then you'll call ZipClose() to close that archive (and delete any MEMORY buffer).
Note: RxZip 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 RxZip sets in your script, you should avoid naming any of your own variables ZipErr or ZipHeading.