The PCK block describes a package in the current or an external archive. This can only be specified in the HEAD block. At least one package must be specified to make WarpIN do anything meaningful.

See the "Installation Scripts" page for an overview where this tag should be placed. See "Minimum script for one package" for a sample script with a simple PCK tag.

The <PCK> ... </PCK> block has the following syntax:

<PCK INDEX=x
     PACKAGEID="vendor\application\package\major\minor[\revision]"
     TITLE="title"
     [EXTERNAL="[REQUIRED|]archive"]
     TARGET="path"
     [BASE] [FIXED] [SELECT] [NODESELECT]
     [REQUIRES=index]...
     [REQUIRES="vendor\application\package\major\minor[\revision]"]...
     [CONFIGSYS="statement[|modifiers...]"]...
     [REGISTERCLASS="classname|dllpath"]...
     [REPLACECLASS="oldclassname|newclassname"]...
     [CREATEOBJECT="[REPLACE] classname|title|location[|config]]"]...
     [EXECUTE="[ context ] execfile params"]...
     [CLEARPROFILE="profile[\application[\key]]"]...
     [WRITEPROFILE="profile\application\key|string"]...
     [KILLPROCESS="filename"]...
>package description displayed to the user</PCK>
In between the <PCK> and </PCK> tags, you must specify the package description as it should be displayed to the user. This will be shown in a tooltip control ("bubble help") if the user moves the mouse over a package on the container page and leaves it there for a second. This description will also be stored in the global database so that it is available during de-installation too.

The opening <PCK> tag can have the following attributes:


INDEX=x
Required. This specifies the index of the package in the current archive (i.e. a decimal number). Since packages are referenced by number in the archive, WarpIN cannot find a package if you don't specify this number and will abort with an error message.

This must be 1 or greater; an index of 0 is not supported. Specify the same package number here as on the WIC.EXE command line when creating the archive.

Note that this index only has to be unique for the archive to which the script belongs. It is not stored in the global database and only used while the archive is opened by WarpIN. To identify the package after installation, WarpIN will use the PACKAGEID attribute (below).

PACKAGEID="vendor\application\package\major\minor[\revision]"
Required. This identifies the package for the global database. From this identification string, WarpIN determines whether the package is already installed on the computer and, if so, whether the installed package is older or newer than the package in the archive.

The ID string must consist of exactly five or six substrings, separated by backslash ("\") characters. The substrings are:

  1. vendor: your company or personal name. This is displayed to the user.
  2. application: the name of the application to which this package belongs. Since only packages, not archives, are stored in the global database, this groups applications together. This is displayed to the user only in database mode.
  3. package: package ID. This is only stored in the global database to identify the package. This is displayed to the user only in database mode. In install mode, the user sees what is specified with the TITLE attribute instead (below).
  4. major: the major version number of the package.
  5. minor: the minor version number of the package.
  6. revision: the revision version number of the package. This is optional (if you prefer to use Linux-like version numbering); if the revision is not specified, this is assumed to be 0.

Example:
PACKAGEID="SuperSoft\Super Word Processor\SpellingDict\1\0"

Notes:

  1. WarpIN package ID's are case-sensitive. SUPERSOFT is not the same as SuperSoft.
  2. If you use ASCII characters above 127 (such as German umlauts), you should set the CODEPAGE attribute to the WARPIN tag also to make sure these strings work on all computers with all codepages. Otherwise WarpIN's string comparisons might fail later.
  3. You can use spaces in the substrings.

TITLE="title"
Required. This specifies what will be displayed on the Container page in WarpIN. This can, but does not have to be, the same as the "package" substring in the PACKAGEID attribute.

This is also stored in the global database and re-displayed during de-installation. However, this is purely informational and not used to identify the package. In the above example, you would probably specify TITLE="Spelling dictionary".

EXTERNAL="[REQUIRED|]archive"
Optional. This marks a package as "external", which means that this package is not contained in the archive which holds the script, but in the archive archive instead.

WarpIN only searches for archives in one directory, the directory where the original archive (the one WarpIN was started with, whose script is used) resides.

If archive is not found in that directory, the package is silently ignored (not displayed on the container page and not installed). This is useful for installing several National Language Support (NLS) packages to an application so that the user does not have to download them all.

By contrast, if REQUIRED is also specified, WarpIN will fail if the package is not found.

TARGET="path"
Required. This specifies the full path (e.g. "C:\TEST") which WarpIN will initially propose to the user as the installation path for the package. Normally, the user can then change this target path, unless you also specify the FIXED attribute (below).

This attribute supports macro resolution.

Note: In order to save the user from having to change the target path for every package that is installed, WarpIN supports two predefined environment variables called WARPIN_DEFAULTAPPSPATH and WARPIN_DEFAULTTOOLSPATH. It is strongly recommended for archive creators to use one of these two variables in the TARGET attribute. See "Script variables" for details.

Example:

TARGET="$(WARPIN_DEFAULTAPPSPATH)\SuperWord"
TARGET="$(WARPIN_DEFAULTTOOLSPATH)\SuperUtility"
TARGET="?:\OS2\DLL"
TARGET="$(MMBASE)\DLL"

BASE
Optional. If you specify this keyword, the package's path is considered a path on which the paths of other packages depend. That is, if the user changes the path of this package on WarpIN's container page, WarpIN goes through the paths of the other packages and automatically updates them too if it finds the old base path in the paths of other packages.

Example:

<PCK INDEX=1 ... TARGET="C:\TEST" BASE>Package 1</PCK>
<PCK INDEX=2 ... TARGET="C:\TEST\SUBDIR">Package 2</PCK>
<PCK INDEX=3 ... TARGET="D:\OTHER">Package 3</PCK>
If the user changes the path of the base package (index 1) to "D:\TEST2", the path of package 2 will automatically be changed to "D:\TEST2\SUBDIR". However, package 3 will not be changed since it does not contain the "C:\TEST" substring.
FIXED
Optional. If you specify this keyword, the path of this package specified by the TARGET attribute cannot be changed by the user. Otherwise the user may change this on WarpIN's container page. This is useful for files which must be written to the OS/2 system directories.
SELECT
Optional. If you specify this keyword, the package is selected for installation per default. Otherwise, it will not be selected.
NODESELECT
Optional. If you specify this keyword, the package cannot be deselected. It will always be selected for installation. Useful for "base" packages on which other packages depend.

This does not store dependencies in the database. For more complicated dependencies, you should use the REQUIRES attribute (below).

REQUIRES="vendor\application\package\major\minor[\revision]"
REQUIRES=index
Optional. This allows you to specify a certain package which must be installed for your package to work.

If a string is specified in quotes, this works just as in the PACKAGEID attribute. This is useful if a package in your product is an add-on to some other software which is distributed in WarpIN archive format also. This requires you to know the ID string of that package.

If a decimal number only is specified (without quotes), this references the package in the current archive with the index index, which must exist. Internally, this will then store the PACKAGEID of that package as a requirement, so this is just a shortcut so you don't have to retype those package IDs all the time. You can, of course, also specify the package ID string of another package in the archive instead. As opposed to the NODESELECT attribute, this does store a dependency in the database.

Note that in this context, the version substring ("major\minor[\revision]") is understood as the minimum version of that package which is required for your package to work. Any installed higher version will be accepted by WarpIN. Also, if you specified the index number and a higher version of that package is already installed, WarpIN will accept that as well.

When a package ID is specified, WarpIN will query the user computer's global database for the specified package. If that package is not installed or too old, WarpIN will give the user a warning message.

You can specify this attribute more than once per package.

CONFIGSYS="statement[|modifiers]..."
Optional. This allows you to update the CONFIG.SYS file, depending on the "statement" and optional "modifiers".

If this is specified for any package which has been selected for installation, WarpIN will display a corresponding checkbox on the "System Configuration" page (see the PAGE tag for more on that).

This supports macro resolution.

See "The CONFIGSYS attribute" for details about this (fairly complex, but flexible) attribute.

You can specify this attribute more than once per package.

REGISTERCLASS="classname|dllpath"
Optional. Registers the SOM class classname with the WPS, which must reside in the dllpath dynamic link library (DLL).

There can be several such attributes per package, all of which will be processed in the order specified in the script.

If this is specified for any package which has been selected for installation, WarpIN will display a corresponding checkbox on the "System Configuration" page (see the PAGE tag for more on that).

Keep in mind that WPS class names are case-sensitive. Also, using this tag requires that the WPS be running while WarpIN is working on the archive, or registering will fail.

"dllpath" must be the full path name of the DLL containing the class. If this DLL resides on the LIBPATH, no path is required though. It is not recommended however to place WPS DLL's on the LIBPATH, because this makes de-installation more difficult.

The "dllpath" substring supports macro resolution.

Example: <PCK INDEX=2 ... REGISTERCLASS="XFolder|$(1)\bin\xfldr.dll">

REPLACECLASS="oldclassname|newclassname"
Optional. Replaces the WPS class "oldclassname" with "newclassname". "newclassname" must have been registered using the REGISTERCLASS attribute before replacing.

Keep in mind that WPS class names are case-sensitive. Also, using this tag requires that the WPS be running while WarpIN is working on the archive, or replacing classes will fail.

There can be several such attributes per package, all of which will be processed in the order specified in the script. All REGISTERCLASS attributes are processed before the REPLACECLASS attributes by WarpIN.

CREATEOBJECT="[REPLACE] classname|title|location[|config]"
Optional. Creates a WPS object. This is similar to the REXX SysCreateObject function, except that due to the HTML-like syntax you cannot use quotes in the argument to this attribute. I hope this is acceptable. The different substrings need to be separated by "|" characters.

Keep in mind that WPS class names are case-sensitive. Also, using this tag requires that the WPS be running while WarpIN is working on the archive, or creating the objects will fail.

There can be several such attributes per package, all of which will be processed in the order specified in the script, so you should create folders before program objects, for example.

Parameters:

REPLACE
Optional. Just as the "R" parameter to SysCreateObject. Note that this must be specified first.
classname
The WPS class of the new object. All REGISTERCLASS attributes are processed before the CREATEOBJECT attributes by WarpIN.
title
The title of the new object. Do not enclose this in quotes, and do not use commas.
location
Where the object should be created. This can either be an object ID (e.g. "<WP_DESKTOP>" or a full path.

The "location" substring supports macro resolution.

config
Optional class-specific setup strings. Everything coming after the last comma is considered to be the setup string so you can use more commas here.

The "config" substring supports macro resolution.

Note: Even though the config substring is optional, it is strongly recommended to always use an object ID setup string (like "OBJECTID=<APP_OBJECT>"), because otherwise WarpIN will not be able to delete your WPS objects upon de-installation.

Always terminate the setup string with a semicolon because some older versions of OS/2 (without fixpaks) get confused otherwise. Also, the OBJECTID= setup string should always be the last setup string for the same reason.

Example: This will create a "SuperWord" folder on the Desktop and a program object for the "suprword.exe" executable in that new folder, using the target path specified with this package.

<PCK INDEX=1 ...
    CREATEOBJECT="WPFolder|SuperWord Installation|<WP_DESKTOP>|OBJECTID=<SUPERWORDFOLDER>;"
    CREATEOBJECT="WPProgram|SuperWord|<SUPERWORDFOLDER>|EXENAME=$(1)\bin\suprword.exe;OBJECTID=<SUPERWORD>;"
>

EXECUTE="[ context | ] execfile params"
Optional. This will execute a program after the package has been installed. This might be useful if you need to have additional configuration performed which is not supported by WarpIN keywords directly.

execfile will be started in a separate session using "CMD.EXE /C execfile params" so that you can also start a REXX script. This attribute gets processed after all files have been unpacked, so you can specify a program here which is part of the package. Both "execfile" and "params" support macro resolution.

context is an optional parameter specifying what the program does. If this is specified, this must come before execfile and must be terminated using a | character. context can be one or more of the following:

According to the context flags, the respective checkboxes on the "Configure" page will be set. If the user disables the corresponding checkbox, the program does not get called. If you do not specify the context, your program will always get called.

You can specify this attribute more than once per package.

CLEARPROFILE="profile[\application[\key]]"
Optional. Here you can specify profile (INI file) data which WarpIN should clean up upon de-installation of this package. Note that this attribute is only for de-installation. If you wish to write string data into a profile, use the WRITEPROFILE attribute (below).

We strongly recommend specifying this attribute if your application stores additional data in the system profiles.

You can specify this attribute more than once per package.

"profile" specifies the INI file which should be cleaned up upon de-installation. This can be "USER" or "SYSTEM" for the user or system profiles (usually OS2.INI and OS2SYS.INI) or an explicit full path specification of an INI file.

The profile substring supports macro resolution.

"application" specifies the application to be cleaned up in the profile. If this is not specified, the whole profile is deleted. (This is prevented for the user and system profiles, of course.)

"key" specifies the key to be cleaned in "application" of "profile". If this is not specified, the whole application is deleted.

WRITEPROFILE="profile\application\key|string"
Optional. Here you can specify a string which should be written to the given profile. "profile", "application", and "key" specify the location where to store the string (as with the CLEARPROFILE attribute above), while "string" specifies the string to store. As opposed to CLEARPROFILE, all of these must be specified here.

You can specify this attribute more than once per package.

The profile and string substrings support macro resolution.

WarpIN does not support writing binary data to profiles, but strings only. If you need binary data, your application must do this by itself, or specify a program using the EXECUTE attribute which does this on install.

The data specified here will be removed upon de-installation.

KILLPROCESS="filename"
Optional. Specifies a process that needs to be killed (using DosKillProcess) during installation or de-installation before files can be overwritten or deleted.

You can specify this attribute more than once per package.

Using this is strongly recommended for applications which have a daemon process running which locks files, especially if that process installs a system PM hook (using WinSetHook, a la NPS WPS). Even though WarpIN is capable of replacing files which are currently in use (using the DosReplaceModule API), this method must not be used on such processes and DLLs, because the hook DLL has become part of every single PM process on the system, and unlocking such a DLL will never unload the DLL until a system reboot or might even solidly hang the system.

You can also use this tag with any other application to make sure it's not running. However, this invokes DosKillProcess on that process, which is not the most subtle way of terminating an application, because the application gets no chance to store its data.

So have the process which installs the hook killed using this attribute. WarpIN determines automatically whether this is necessary.

Example: KILLPROCESS="npswps.exe" will killl NPS WPS (if it's running) before files are overwritten or removed for the current package.