Where a patch file is designed to update a single file, a patch package is a collection of updates which are applied on a target system. One important aspect of creating a patch package is that the patch is being created for distribution to a target system, so the directory structure and files must match how they are installed on the target system, not the development system. The simplest way to do this is to simply install the original version of the product or files on the system as though you were the end user. Then, install the updated version of that product in a different directory, again as if you were the end user. These two directories can then be used as the reference and update directories on which the patch package is generated. For the examples used with the package functions, we'll use two groups of files which represent two different versions of a product. The directory version1 will contain subdirectories and files in the original version, and the directory version2 will contain the updated files.

To create the patch package, place the Package control on a form and use the following code:

' Create a package file based on the differences between the files
' in two directories

Dim strOldDir As String
Dim strNewDir As String

strOldDir = "\product\version1"
strNewDir = "\product\version2"

Package1.FileName = "update.pkg"
Package1.Password = "secret"
Package1.Options = apIgnoreMissing Or apIgnoreFileTime Or apOverwrite
Package1.Platform = apDefaultPlatform

On Error Resume Goto CreateFailed
Package1.Create strOldDir, strNewDir, , , apRecursiveUpdate
Exit Sub

CreateFailed:
MsgBox Err.Description
Exit Sub

The FileName property specifies the name of the package file to create.

The Password property specifies the password that was used to secure the package file when it was created.

The Options property specifies the options to be used when applying the package. In this case, there are three options which are used. Note that if no options are explicitly specified when the package is being applied, these are the options that will be used. The first option is apIgnoreMissing which is useful when the target system may not contain all of the files in the package. For example, most installations will allow you to specify whether or not you want a minimal install, a complete install or a custom install in which the end-user may select certain components which are to be installed. Because there is no way for you to know ahead of time which type of installation a user has selected, you simply include all files in the package. This option then tells ActivePatch to not return an error if the file doesn't exist because the user may not have chosen to install it. The second option is apIgnoreFileTime and serves the same function as in the patch example. The third option is apOverwrite which specifies that ActivePatch should always make sure that updated files are overwritten, even if the file is new and not expected to exist on the target system, or if the file has the read-only file attribute set.

The Platform property is set to identify the target platforms on which the package may be installed. This is used to control the application of a package so that the updates can only be applied on the appropriate platform. The value used in this case is apDefaultPlatform, which specifies that the package may be applied on any system.

The Create method is then called, with the first parameter specifying the name of the directory that contains the original version of the files, and the second parameter specifying the directory that contains the updated version of the files. The next parameter specifies the name of the default installation directory. In most cases this optional parameter is not needed, and may be omitted. The following parameter specifies those files which are to be excluded from the package. Multiple wildcards may be specified by separating them with a semicolon. For example, to exclude all files with a .tmp and .bak extension, the exclude mask string would be "*.tmp;*.bak". If no files are to be excluded, then this parameter does not need to be specified. The last parameter specifies any options that are to be used when creating the package. In this case, we specify a single option, apRecursiveUpdate which tells ActivePatch to recursively search any subdirectories in the reference and update directories. For a complete list of the flags that can be specified, consult the technical reference.

If the Create method succeeds, the package file will be created. If the method fails, the error trap is triggered and a description of the error is displayed.