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[\fixlevel]]" TITLE="title" [EXTERNAL="[REQUIRED|]archive"] TARGET="path" [BASE] [FIXED] [SELECT] [NODESELECT] [LONGFILENAMES] [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
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).
Note: Package indices above 30000 are reserved. See
WIC.EXE -- Add mode for details.
PACKAGEID="vendor\application\package\major\minor[\revision[\fixlevel]]"
The ID string must consist of exactly five or six substrings, separated by
backslash ("\") characters.
The substrings are:
vendor
: your company or personal name. This is
displayed to the user.
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.
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).
major
: the major version number of the package.
minor
: the minor version number of the package.
revision
: the revision version number of the package. This
third number is optional; if not specified, this is assumed to be 0.
fixlevel
: the fixlevel version number of the package. This
fourth number is optional as well; if not specified, this is assumed to be 0.
(The fixlevel requires WarpIN V0.9.20 to be running.)
PACKAGEID="SuperSoft\Super Word Processor\SpellingDict\1\0"
Notes:
SUPERSOFT
is not the
same as SuperSoft
.
WARPIN
tag also to make sure these
strings work on all computers with all codepages.
Otherwise WarpIN's string comparisons might fail later.
TITLE="title"
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"
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.
The script in the external archive
does not get parsed; WarpIN will simply check archive
for
whether it contains a package with the index that was specified with this
PCK
tag. You may use the same external archive
for multiple packages (with different indices, of course).
In other words, if you use external archives, package indices must be unique
among all archives.
TARGET="path"
"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
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
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
NODESELECT
This does not store dependencies in the database. For more complicated dependencies,
you should use the REQUIRES
attribute (below).
LONGFILENAMES
REQUIRES="vendor\application\package\major\minor[\revision]"
REQUIRES=index
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]..."
"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"
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"
"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]"
"|"
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
classname
REGISTERCLASS
attributes are processed before the
CREATEOBJECT
attributes by WarpIN.
title
location
The "location"
substring supports
macro resolution.
config
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"
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:
CONFIGSYS
: the program modifies the CONFIG.SYS file.
REGISTERCLASS
: the program modifies the WPS class list (by registering
and/or replacing classes).
CREATEOBJECT
: the program creates WPS objects.
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]]"
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"
"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"
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.