This chapter describes how to use the %Installer utility to create an installation manifest describing a specific Caché configuration and use it to generate code to configure a Caché instance. The chapter discusses the following topics:

The %Installer utility lets you define an installation manifest that describes a specific Caché configuration, rather than a step-by-step installation process. To do so, you create a class that contains an XData block describing the configuration you want, using variables that contain information usually provided during installation (superserver port, operating system, and so on). You also include in the class a method that uses the XData block to generate code to configure the instance. (You can copy and paste this method from this book.)

Once you have defined the manifest, you can call it during installation, from a Terminal session, or from code. The manifest must be run in the %SYS namespace.

Creating a Class That Defines a Manifest

To create a class that defines an installation manifest, create a class as follows:

Within the context of a <Namespace> tag  after the databases and their mappings have been defined  globals can be loaded, and routines and classes can be loaded and compiled using <Import> tag. Class methods can be invoked using the <Invoke> tag. Invoked class methods can execute routines and access globals that have been imported.

Optionally, you can define variable pairs with the <Var> tag; each variable must specify a name and value. When the value for the <Var> is needed, the name is referenced by the ${NameAssigned} syntax.

The PasswordVar parameter of the <User> tag specifies the variable containing the password for the user; for example, by defining PasswordVar="Pwd", you are specifying that the value of the variable Pwd is the password for a user. There are a variety of ways to populate this variable, but it is ultimately up to you to do this. You might consider using a remote method invocation to another instance of Caché or a web service; the problem with these approaches is that the server that is installing Caché may need internet access. Other possibilities include importing the method you are using to the instance you are installing, or adding a client-side form to the install that prompts for users and passwords, which can be passed to your manifest.

Using the Security.Users class on a staging instance of Caché or Ensemble, as follows:

You can define messages to be added to the log by incorporating <Log> tags in your class, in the following format:

<Log Level="<level>" Text="<text>"/>

The log level must be in the range of 0 to 3, where 0 is none and 3 is verbose; if the log level specified in the setup() method is equal to or greater than the Level property in the <Log> tag, the message is logged. The text is limited to 32,000 characters.

You set the log level via the second argument of the setup() method (for more information, see Using the Manifest later in this chapter). Since this cannot be passed to the manifest from the install, you must set it in the class as follows:

You can direct where messages are displayed via the fourth argument (%Installer.AbstractLogger) of the setup() method; for example, if you instantiate a %Installer.FileLogger object referencing an operating system file, all %Installer and log messages are directed to that file. (Without this argument, all messages are written to the primary device if setup() is called directly, and are ignored if it is executed by the installer.)

<Manifest> Tags

Following are descriptions of the tags (in alphabetical order) you can use within the XData block of your manifest class.

Some tags can contain expressions (strings) that are expanded when the manifest is executed. There are three types of expressions that can be expanded, as follows:

Expands to the value of the specified user variable (defined with the <Var> tag, as described in this section) or predefined variable (listed in the section Variables Available within <Manifest>). Examples of this type of expression can be found within this section.

Expands to the specified Caché Object Script expression (which must be properly quoted).

Parameter expressions are expanded at compile time, which means they can be nested within variable and COS expressions. Addtionally, variable expressions are expanded before COS expressions and thus can be nested within the latter.

Important:

Null arguments cannot be passed in tags in a manifest class. The <Arg/> tag passes an empty string, equivalent to <Arg=""/>, not null.

Note:

The value shown in square brackets ([]) is the default used for a property if it is not specified explicitly.

Note that if you use the export technique, you cannot pass arguments directly to the setup() method. However, you can do the following:

On Microsoft Windows systems (see the chapter Installing Caché on Microsoft Windows), you can modify the .msi install package to pass variable name/value pairs to the setup() method. You can also use command-line arguments with the installer to pass the location of the exported manifest class, variable pairs, log file name, and log level, as shown in the following example:

The following class creates a namespace (MyNamespace) and three databases; two of the databases are defined as the default databases for globals (MyDataDB) and routines (MyRoutinesDB), while the third database (MyMappingDB) is a globals database that overrides the default database mapping for t* globals in the MyNamespace namespace.