Last update: 08-fev-2004 08:47:21

RSP Zip Compressor Commands

This section has description of usage of the commands used to pass information to the RSP Zip Compressor development tool series

Commands are the way to pass information about what to do with the RSP Zip Compressor development tool

It was created to avoid problems to correctly pass the required information to the compressor or uncompressor like destination  path , destination zip file  , zip file to unzip , temporary path  , whether it will recurse on subfolders or not during compression , whether it will compress system and hidden files and many more possible options

With the commands the argument passed is intuitive , so you understand exactly what you mean , and what the control will do to you , solving very hard to debug problems

And the control can catch at initialization time wrong information passed , avoiding possible problems before the execution

In case of problems the control will return information about what is wrong , making it more easy to track bugs

You only need to learn once about the commands and you never will forget what each command mean

The commands are constructed as a sequence of strings added together to result in the complete command , the delimiters are the characters <> and =  , like this <password="password">

This mean the command password with the value "password"

You obviously will understand that you are passing the password to the command as 'password'

The character "" isnot obligatory , so the string
<password="password">
and
<password=password>
Will result in the same information passed

The control can handle spaces in the middle of the arguments without problems
Then a command like this :
<password=my password>
Will be correctly understood as the password 'my pasword' being passed

The result of the creation of the command will be a series of commands in a string like this

<item1=item 1 value><item2=item 2 value><item3><item4>
And so on

After the end of the creation of the command just pass the string to the RSPZipCompress or the RSPZipUncompress functions

With future updates of this control we don't plan to broke compatibility with older versions , then , new commands can be added but what was working with older versions , will work with future versions without problems

password : This command will define the password to be used when decompressing the zip file , if not used , no password will be used to decompress the file , then if the zip is password protected an error will be returned
example using VB code:
ret = RSPZipUncompress("<password=my password>")

test-zipfile : This command will make the decompressor to decompress the selected files to the memory and check the CRC of all the selected files , if the file is damaged an error will be returned with description
example using VB code:
ret = RSPZipUncompress("<test-zipfile>")

file-extraction-mode : This command will define whether the files will be overwritten in the destination folder or not overwritten or freshen , in case of freshen , the files will only be extracted if the destination files exist on the disk and are older than the files available on the zip file , the valid arguments to this command are overwrite , don't-overwrite or freshen-files , if an invalid option is passed as an argument to this command and error will be returned with description , if this command is not passed , the control will overwrite by default
example using VB code:
ret = RSPZipUncompress("<file-extraction-mode=don't-overwrite>")
or
ret = RSPZipUncompress("<file-extraction-mode=overwrite>")
or
ret = RSPZipUncompress("<file-extraction-mode=freshen-files>")


zipfile : This command will define the zip file to be extracted to the destination directory , the control has full support to UNC paths , the argument to this command need to be a zip file including full path information , this command is obligatory in any call to the decompression function
example using VB code:
ret = RSPZipUncompress("<zipfile=c:\mypath\myzip.zip>")
or
ret = RSPZipUncompress("<zipfile=c:\\UNCpath\sharedfolder\myzip.zip>")

files-selection : This command will select what files in the zip file will be processed , if an "*.*" is used , then all files will be processed , and the selection is case insensitive , if a selection like this "*.H" is used , all files with an extension .h and .H will be extracted , notice that you don't need to use "" to pass arguments , even with long path names , the parser will evaluate each command and argument as required , this command is obligatory in any call to the decompression function
example using VB code:
ret = RSPZipUncompress("<files-selection=*.h>")
or
ret = RSPZipUncompress("<files-selection=my file to extract.mdb>")

destination-path : This command will define the path where the files will be extracted , if the command <test-zipfile> is used , then this command is irrelevant , since to test the zip file the decompressor will extract to the memory , this command has full UNC path support , and the parser will check whether the destination path is valid , if the path is not valid an error and description will be returned , this command is obligatory in any call to the decompression function when the command <test-zipfile> isnot used
example using VB code:
ret = RSPZipUncompress("<destination-path=c:\mypath to extract\path1>")
or
ret = RSPZipUncompress("<destination-path=\\UNCpath\mysharedfolder>")

In order to execute the decompression you need to construct a complete command like this

ret = RSPZipUncompress("<password=my password><file-extraction-mode=don't-overwrite><zipfile=c:\mypath\myzip.zip><files-selection=*.h><destination-path=c:\mypath to extract\path1>")

In the case above , the file "c:\mypath\myzip.zip", will be extracted to "c:\mypath to extract\path1" , and only the files "*.h" will be extracted , and it will not overwrite the files in the destination

ret = RSPZipUncompress("<test-zipfile><password=my password><zipfile=c:\mypath\myzip.zip><files-selection=*.h>")

In the case above , the file "c:\mypath\myzip.zip", will be tested in memory for errors for all the files that nas an .h as extension

The commands are constructed in any sequence , the delimiters <> define where a command begin and where it end , there is no sequence to follow when grouping commands , and you can put spaces between commands like this:
ret = RSPZipUncompress("    <password=my password>    <file-extraction-mode=don't-overwrite>   <zipfile=c:\mypath\myzip.zip>   <files-selection=*.h>   <destination-path=c:\mypath to extract\path1>   ")

You only need to be careful with spaces in the arguments to the command , like this:
ret = RSPZipUncompress("<password=my password>")
is equal to
ret = RSPZipUncompress("  <   password  =my password>   ")
but it is not equal to
ret = RSPZipUncompress("  <   password  =my pass word>   ")
In this case the password now is "my pass word" and will be executed incorrectly internally

With the parser it is more easy to detect errors in the information passed to the compressor or decompressor

It will avoid ambiguities on the compression or decompression code , since the parser will evaluate each command and return an error code if the command is not accepted

And it will inform about missing commands or modifications required in the commands in order to work

With the parser it will be more easy to compress or decompress zip files since you only need to know about the commands and all the commands are intuitive making it a good solution to use zip compression in any application using only a few lines of code , and with full zip compression error handling

For each error , a description of the error will return , with the description it is very easy to understand what goes wrong , and how to avoid the same error in the future

  <set-zip-temp-path>  This command will define the temporary path to be used for the temporary files generated during the compression

This command isnot obligatory, if it is missing the default user temp path will be used to the compression function

If the path don't exist , it will be created , in case of error , an error and description will be returned

example
<set-zip-temp-path="c:\temp">

   
<delete-entries-on-zipfile> This command will make the control delete entries on a zip file instead adding files to it

If the selection of files is *.txt , then all the .txt files will deleted in the zip file

example
<delete-entries-on-zipfile>
   
<password> This command will define the password to be used to compress the files

This command is not obligatory , if it is missing the zip file will be compressed without a password
   
example

<password=my password>
   
<recurse-on-subfolders>  This command will make the compressor to recurse on subfolders when searching for the selected files to compress

This command is not obligatory , if it is missing the compression will not recurse on subfolders

example
<recurse-on-subfolders>

<include-system-and-hidden-files> This command will instruct the compressor to include system and hidden files in the zip file

This command is not obligatory , the default method is to always add system and hidden files

This will not occur if the command exclude-system-and-hidden-files is used

example
<include-system-and-hidden-files>


<exclude-system-and-hidden-files> This command will make the compressor to exclude system and hidden files during the compression

This command is not obligatory , the default method is to always add system and hidden files , using this command will change it to don't include system and hidden files

example
<exclude-system-and-hidden-files>

<zip-compression-mode> This command will define what will be the way that the compressor will update or replace or freshen files on the destination zip file

It has a series of possible arguments that are:
update-entries-if-newer
freshen-files
add-to-zipfile
create-new-zipfile

update-entries-if-newer  This argument will make the compressor to replace (update)  an  existing entry in the zip archive only if it has been modified more recently than the version already in the zip  archive

example
<zip-compression-mode=update-entries-if-newer>


freshen-files  This argument will make the compressor to replace (freshen) an  existing  entry  in  the  zip archive  only if it has been modified more recently than the version already in the zip archive; unlike the update option ( update-entries-if-newer ) this will not add files that are not already in the zip archive.

example
<zip-compression-mode=freshen-files>

 add-to-zipfile This argument will make the compressor to create a new zip file if the destination zip file don't exist or update a zip file if the destination zip file exist , this is the default zip execution

example
<zip-compression-mode=add-to-zipfile>

create-new-zipfile This argument will make the compressor to delete the destination zip file if it exist and create a new zip file , this command is dangerous since it can delete a zip file , use it with cautions , it is only required when you really want to create a new zip files instead updating it , normally it will not be used , since updating a zip with a file will have the same effect

example
<zip-compression-mode=create-new-zipfile>

<compression-level> This command will define what will be the compression level used during the zip execution

It can range from 0 to 9

0 to store only , 9 to the maximum compression

It this command is missing the level 6 will be used by default

example
<compression-level="9">
   
<directory-with-the-files-to-compress> This command will define what is the folder that has the files that you want to compress

This is an obligatory command

If you want to compress all the files in the folder c:\mytemp , then pass the argument to this command as c:\mytemp
   
If the path don't exist , an error will be returned

example
<directory-with-the-files-to-compress="c:\windows">

<destination-directory> This command will define the destination directory to the zip file

This is where the zip file will be created or updated

This command is obligatory

If the destination directory don't exist , it will be created

If the path cannot be created , and error and error description will be returned

example
<destination-directory="c:\backup">

<destination-zipfile> This is the destination zip file to be created or updated

This command is obligatory , since you always need a zip file for any command available in the compression

The command defines only a zip file name , and not path , since the path is the destination-directory command

If the zip file don't exist , it will be created , if the file cannot be created an error will be returned


example
<destination-zipfile="myzip.zip">
  

<files-selection> This command will define the files that you want to compress

To compress all files use *.*
To compress a unique file use the name of the file as the argument , so , to compress the file mydatabase.mdb , pass mydatabase.mdb as the argument

It only accept one selection , for many selections call the compression function for each required selection
   
Thus , if you want to add *.txt and *.mdb to the zip file , make two calls , one with *.txt and another with *.mdb using the same destination zip file

Future versions of this control will have multiples files selections on a unique call

example
<files-selection="mydatabase.mdb">
or
<files-selection="*.*">
 

Future versions of this control will have several new commands , for each new command new entries in this page will be added with description and example code

In order to execute the compression you need to construct a complete command like this

<include-system-and-hidden-files><zip-compression-mode=add-to-zipfile><compression-level=6><directory-with-the-files-to-compress=c:\directory with the files to compress\><destination-directory=c:\my destination directory><destination-zipfile=myzip.zip><files-selection=*.*>

When passing it to the control use the following sintax

RSPZip1.RSPZipCompress ("<include-system-and-hidden-files><zip-compression-mode=add-to-zipfile><compression-level=6><directory-with-the-files-to-compress=c:\directory with the files to compress\><destination-directory=c:\my destination directory><destination-zipfile=myzip.zip><files-selection=*.*>")

In the case above the compression will include system and hidden files , the mode is to add to the zip file , the compression level is 6 , the directory with the files that you want to compress is 'c:\directory with the files to compress',  the destination directory is 'c:\my destination directory' , the destination zip file to be created is 'myzip.zip' and the files selected are all files

As you can see , it is intuitive , and if problems occur the control will inform what is wrong or what is missing in the command since all the information passed is checked to avoid possible bugs

The future releases will have more commands available




Return to the RSP ZIP Compressor development tools series homepage