IIP macro replacement

A very important feature of integrated installation packages (IIP) is the ability to use macros to help automate the installation of included installation packages.

This page provides the following information about IIP macros:


Use of macros in an IIP

We can use predefined macros to make the IIP more flexible and to automate how certain contributions are installed without having to specify everything in the build definition wizard during IIP creation. For example, we can install two different installation packages in the same location (or relative to the same location) without having to manually specify that location twice in the IIP build definition wizard. The installation location of the first package can be automatically assigned to the -installLocation option of the second package, thereby causing it to default to that location. Note that the user can change this value during install time if you allowed this during IIP creation. Because macros are not resolved until IIP installation, they can be used not only by the user who creates the IIP, but also by the user who invokes it. Both the build definition wizard and the IIP installation wizard will provide convenient ways for users to leverage macros without having to manually edit the option strings to create or modify macros directly

Not all options supported by a contribution can be referenced in a macro. Only the -installLocation and the –silent options can be referenced in the $RESV, $OPTV, and $OPTS macros at this time.

Use the following macros in the IIP:



This takes the result value of the specified invocation and replaces the macro with that value, where <Invocation_ID> specifies which contribution invocation in the IIP provides the named result value. The invocation ID is needed to resolve any ambiguity that might occur if different contributions use the same result value names or if there are multiple invocations of the given contribution. For example, if an IIP contains the application server installation package (Invocation_ID = 6.1.0-WS-WASBase_1-1) and the Feature Pack for Web Services install package, then it is likely you would want the feature pack to be automatically installed into the same place as the appserver. This can be achieved by passing the following option into the feature pack installation program on the IIP installation command line:

 -OPT installLocation=$RESV{6.1.0-WS-WASBase_1-1:installLocation} 
Since both the appserver installer and the feature pack installer support the-installLocation result value, this ensures that whatever installation location was used for the appserver will be automatically passed into the feature pack installer. If, during IIP installation, the referenced invocation has been suppressed by the user (in other words, the user chose not to install that specific package) and the invocation containing the reference has not been suppressed, then an error is generated and the installation of the IIP is not allowed to continue because it would not be possible to resolve the macro. For example, if the appserver has already been installed outside of the IIP, and you try to install a feature pack package with the IIP using a macro which resolves to a deselected appserver package install location, the installation will fail. Specify the install location for the feature pack without using this macro. The user must do one of four things to continue if a macro cannot be resolved:

  • Change the macro to reference a different invocation which has not been suppressed.

  • Enable the referenced invocation.

  • Disable the invocation containing the reference.

  • Remove the macro.



This will take the value of the option with the given name, and replaces the macro with that value, where <Invocation_ID> specifies which contribution invocation in the IIP supports the named option. This is needed in order to resolve any ambiguity that might occur if different contributions use the same result value names or if there are multiple invocations of the given contribution. It is an error if, during IIP installation, the referenced option cannot be resolved because it was not actually specified on the referenced invocation. The IIP user must either change the referenced invocation to include the option, or change/remove the macro with the reference. It is an error during IIP creation to use this macro to reference an option that does not take a value, for example –silent. In this case the build definition wizard issues an error and the IIP cannot be built.

This example is very similar to the $RESV example with one important exception:

-OPT installLocation=$OPTV{6.1.0-WS-WASBase_1-1:installLocation}

This takes whatever installation location was passed to the application server in the -installLocation option and passes it to the feature pack for its installation location. This will work fine if the application server was installed silently, but if it was installed in GUI mode, then the user could have modified the location in the installation wizard to something else. This macro would still resolve to the original value set during IIP creation. It is better to use the Result Value macro ($RESV) and not the Option Value macro ($OPTV) in this case.



This takes the spec of the option with the given name and replaces the macro with that specification, or with string if it has been provided. The <Invocation_ID> specifies which contribution invocation in the IIP supports the named option. The option specification is a string that represents exactly how the option is specified on the command line, minus any value, for example -OPT installLocation=. This macro is mostly used for options that don’t take any value, like –silent. The string part of the macro allows you to use a string value as the replacement of this macro instead using the referenced option specification directly. This supports those cases where two different contributions might have different options for the same function, in this case silent installation. One of the contributions can use the macro to check if the other contribution was invoked silently, and if so it can then specify its own option for silent invocation using string.

Note that, unlike the $OPTV macro, $OPTS expands to the empty string if the referenced option was not specified on the referenced invocation – this is not an error situation. This is important to support things like the installation mode, where the absence of an option like -silent means that the installer will use the GUI mode. Using this macro to reference an option that does not have a spec will result in an error.

Options which take no values, such as –silent, can also be resolved using macros...


In this case, if the referenced option, –silent, has been specified on the invocation of the appserver contribution 6.1.0-WS-WASBase, then the macro will be replaced by the option spec -silent. If this option was not specified then the macro resolves to the empty string. This allows you to install a set of contributions consistently in silent mode or in GUI mode based on what was specified for one of those contributions. A warning will be issued if the option was not specified on the referenced contribution in case this reference is a user error.


$LOC{[<Contribution_ID>_<Sub_ID> | IIP]}

This macro will resolve to the location of the given package invocation in the IIP, and the result is an absolute path. When a Contribution_ID and Sub_ID are specified, this resolves to the root location of the specified contribution within the IIP. For example, if we have a contribution for the base edition of the application server product for windows, then the root directory of that contribution would be IIP_home/contrib/6.1.0-WS-WASBase/1/WinX32. The following macro example resolves to this directory:


If only IIP is specified, then this value resolves to the root directory, or IIP_home, of the IIP:



$JP{<Java property>}

This macro will be replaced with the current value of the named Java™ property. This can be any property currently known to the Java runtime. For example, during the IIP build definition wizard we are asked to specify the target installation directory of the contribution invocations. By default the target installation directory for a non root user...


This appends /IBM/WebSphere/AppServer to the current user's home directory to complete the directory path.

Related tasks

Related reference


Last updated Nov 11, 2010 1:01:09 PM CST