Condition blocks within PKG files

Condition blocks may be used to control whether parts of the SIS file are skipped. A condition-block may take the form:

IF (condition)
    package-body 
[ ELSEIF (condition) 
    package-body 
] 
[ ELSE 
    package-body 
] ENDIF

The square brackets, above, indicate and enclose conditions within the condition-block statement that are optional.

Note: It is advisable to put brackets around the condition.

`condition`

A condition can be structured in any of the following ways:

Name	Usage
`condition-primitive`	`(condition)`
`AND`	`(condition) AND (condition)`
`OR`	`(condition) OR (condition)`
`NOT`	`NOT(condition)` Note: when using the IF statement with the unary operator NOT, the condition must be contained within braces, e.g.: `IF NOT (MachineUid = 0x101fb3dd)`

`condition-primitive`

where condition-primitive can be:

Name	Description
`attrib=value`	Equal to
`attrib<>value`	Less than or greater than
`attrib>value`	Greater than
`attrib<value`	Less than
`attrib>=value`	Greater than or equal to
`attrib<=value`	Less than or equal to
`exists(filename)`	Tests for the existence of a file
`appprop(uid,propid)`	Retrieves the properties from another registry entry
`package(package_uid)`	Tests for the existence of an installed package
`version(package_uid,rel_operator,v_major,v_minor,v_build)`	Tests for the existence of an installed package and whether its version satisfies the supplied version condition (currently supported within v9.4 and later) v_major = major component of the version (range 0-127); v_minor = minor component of the version (range 0-99); v_build = build component of the version (range 0-32,767)

`attrib`

attrib may be one of the attributes defined in HALData::TAttribute. These attributes correspond to properties of the device's hardware. It should be specified in upper case and without the initial letter E. The following attributes are supported:

PKG variable name	HALData attribute (as retrieved by HAL::Get())
`MANUFACTURER`	`HALData::EManufacturer`
`MANUFACTURERHARDWAREREV`	`HALData::EManufacturerHardwareRev`
`MANUFACTURERSOFTWAREREV`	`HALData::EManufacturerSoftwareRev`
`MANUFACTURERSOFTWAREBUILD`	`HALData::EManufacturerSoftwareBuild`
`MODEL`	`HALData::EModel`
`MACHINEUID`	`HALData::EMachineUid`
`DEVICEFAMILY`	`HALData::EDeviceFamily`
`DEVICEFAMILYREV`	`HALData::EDeviceFamilyRev`
`CPU`	`HALData::ECPU`
`CPUARCH`	`HALData::ECPUArch`
`CPUABI`	`HALData::ECPUABI`
`CPUSPEED`	`HALData::ECPUSpeed`
`SYSTEMTICKPERIOD`	`HALData::ESystemTickPeriod`
`MEMORYRAM`	`HALData::EMemoryRAM`
`MEMORYRAMFREE`	`HALData::EMemoryRAMFree`
`MEMORYROM`	`HALData::EMemoryROM`
`MEMORYPAGESIZE`	`HALData::EMemoryPageSize`
`POWERBACKUP`	`HALData::EPowerBackup`
`KEYBOARD`	`HALData::EKeyboard`
`KEYBOARDDEVICEKEYS`	`HALData::EKeyboardDeviceKeys`
`KEYBOARDAPPKEYS`	`HALData::EKeyboardAppKeys`
`KEYBOARDCLICK`	`HALData::EKeyboardClick`
`KEYBOARDCLICKVOLUMEMAX`	`HALData::EKeyboardClickVolumeMax`
`DISPLAYXPIXELS`	`HALData::EDisplayXPixels`
`DISPLAYYPIXELS`	`HALData::EDisplayYPixels`
`DISPLAYXTWIPS`	`HALData::EDisplayXTwips`
`DISPLAYYTWIPS`	`HALData::EDisplayYTwips`
`DISPLAYCOLORS`	`HALData::EDisplayColors`
`DISPLAYCONTRASTMAX`	`HALData::EDisplayContrastMax`
`BACKLIGHT`	`HALData::EBacklight`
`PEN`	`HALData::EPen`
`PENX`	`HALData::EPenX`
`PENY`	`HALData::EPenY`
`PENDISPLAYON`	`HALData::EPenDisplayOn`
`PENCLICK`	`HALData::EPenClick`
`PENCLICKVOLUMEMAX`	`HALData::EPenClickVolumeMax`
`MOUSE`	`HALData::EMouse`
`MOUSEX`	`HALData::EMouseX`
`MOUSEY`	`HALData::EMouseY`
`MOUSEBUTTONS`	`HALData::EMouseButtons`
`CASESWITCH`	`HALData::ECaseSwitch`
`LEDS`	`HALData::ELEDs`
`INTEGRATEDPHONE`	`HALData::EIntegratedPhone`
`DISPLAYBRIGHTNESS`	`HALData::EDisplayBrightness`
`DISPLAYBRIGHTNESSMAX`	`HALData::EDisplayBrightnessMax`
`KEYBOARDBACKLIGHTSTATE`	`HALData::EKeyboardBacklightState`
`ACCESSORYPOWER`	`HALData::EAccessoryPower`
`SYSTEMDRIVE`	`HALData::ESystemDrive`
`FPHARDWARE`	`HALData::EHardwareFloatingPoint`
`NUMHALATTRIBUTES`	`HALData::ENumHalAttributes`

The following attributes, which are not stored in the HAL, can additionally be specified:

Attribute	Description
`LANGUAGE`	An integer that identifies the language selected by the user at install time. For possible values, see the `TLanguage` enumeration defined in `e32const.h`. Note that the recommended way to install language-specific files is to use language blocks, as described here.
`REMOTEINSTALL`	Deprecated.
`Option<n>`	`0`=option not selected, `1`=option selected.

Condition blocks may be used to ensure that the SIS file installs appropriate binaries for the target platform, for example:

IF FPHARDWARE=0
"\epoc32\release\gcce\urel\myapp.exe"-"!:\sys\bin\myapp.exe.exe";
ELSE
"\epoc32\release\gcce\urel\myappVFP.exe"-"!:\sys\bin\myappVFP.exe";
ENDIF

Functions

The following functions can be used in Software Install PKG files: package() tests for the existence of a given installed package, exists() tests for the existence of a given file or a non-root folder and appprop() retrieves the properties from another registry entry.

package(): this returns true if a package with the specified UID is installed, false otherwise, so the following code installs foo.txt if a package exists with package UID 0x11223344.

IF package(0x11223344)
"foo.txt"-"c:\foo.txt"
ENDIF

exists(): in the following code, if test.txt exists, the file exists.txt is installed.

if exists("c:\test.txt") 
    "text\exists.txt"-"!:\private\01234567\exists.txt"
endif

appprop(): the first parameter to appprop() is the package UID of the other package file in which the property is defined. The second parameter is the propid to retrieve. The following code tests the capabilities of another PKG file that it is dependent upon:

;Dependencies
(0x10000003), 1, 2, 3, {"Depend-EN"}

if (appprop(0x10000003,0) = 1)
   "text\appprop1.txt"-"!:\Documents\appprop1.txt" 
elseif (appprop(0x10000003,0) = 2)
   "text\appprop2.txt"-"!:\Documents\appprop2.txt" 
endif

version(): When installing a SIS file that contains version function conditionals on a device that supports version comparisons (currently 9.4 and later), if the package identified by the package_uid resides on the device and the version of the package satisfies the condition specified by the function parameters, the function returns true. Otherwise, it returns false.

In the following example, if the package identified by UID 0x10000042 has been installed on the device and its version is less than 1.1.1, the condition returns true. If the package does not exist or the package version does not satisfy the condition, it returns false:

if version(0x10000042,<,1,1,1)
  "text\config.txt"-"!:\private\10000042\import\InstTest\config.txt"
endif

When installing a SIS file that contains version function conditionals on a device that does not support version comparisons (currently prior to v9.4), all calls to version() functions evaluate to false. This is even if the installed package has a version value that satisfies the condition.

There are several ways to determine whether a target device supports version() function calls during installation:

using a known product or platform stub SIS file
using a compound condition made up of the package() function and the version() function

The following example shows how to use a known product or platform stub SIS file to identify whether the version() function is compatible.

; VersionCompatibleProductID = 0x101FFFFF    

if package(0x101FFFFF)
; Version supported

  if version(0x10000042,<,1,1,1)
  "text\config.txt"-"!:\private\10000042\import\InstTest\config.txt"
  endif

else
; Version not supported
endif

The following example shows how to use a compound condition made up of package() and version(). It calls the package() function to confirm the presence of a known installed package. It calls the version() function with a condition known to be true (for example, >= 0.0.0) to confirm whether the software installer can use version() functions.

; Example package 0x12345678 is known to be installed in this case

if package(0x12345678) AND version(0x12345678,>=,0,0,0)       
; Version supported
endif

if package(0x12345678) AND NOT version(0x12345678,>=,0,0,0)  
; Version not supported
endif

Notes

Conditional blocks (including language dependent file blocks) are evaluated at the end of the installation. This means for instance that executables launched using FILERUN or FILEMIME statements must not depend on conditionally installed or language-dependent files in the same package file.

Note that most PKG items are valid within a condition block, however the following item types may not be used: