Caché Installation Guide
Creating and Using an Installation Manifest
[Back] 
   
Server:docs1
Instance:LATEST
User:UnknownUser
 
-
Search:    

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:

Overview
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:
The following is an example:
Include %occInclude
Class MyPackage.MyInstaller
{
XData MyInstall [ XMLNamespace = INSTALLER ]
   {
   <Manifest>
      <Var/>
      <If/>
      <Log/>
      <User/>
      <Resource/>
      <Role/>
      <SystemSetting/>
      <ForEach>
         <!--Code for each iteration of named Index key while looping through values-->
      </ForEach>
      <CopyDir/>
      <CopyFile/>
      <Namespace>
         <Configuration>
            <Database/>
            <ForEach>
               <!--Code for each iteration of named Index key while looping through values-->
            </ForEach>
            <Log/>
            <GlobalMapping/>
            <RoutineMapping/>
            <ClassMapping/>
         </Configuration>
         <Compile/>
         <CopyClass/>
         <CSPApplication/>
         <ForEach>
            <!--Code for each iteration of named Index key while looping through values-->
         </ForEach>
         <If/>
         <Import/>
         <Invoke/>
      </Namespace>
   </Manifest>
   }

ClassMethod setup(ByRef pVars, pLogLevel As %Integer = 3, 
   pInstaller As %Installer.Installer, 
   pLogger As %Installer.AbstractLogger) 
   As %Status [ CodeMode = objectgenerator, Internal ]
   {
   #; Let XGL document generate code for this method. 
   Quit ##class(%Installer.Manifest).%Generate(%compiledclass,
      %code, "MyInstall")
   }
}
Key Options
The outermost XML tag, <Manifest>, contains all the information for code generation. There can be as many <Namespace> tags as needed within the <Manifest> tag to define namespaces in the manifest.
A <Configuration> tag, which is located inside a <Namespace> tag, is required only if databases and/or mappings are being defined. There must be as many <Database> tags within the <Configuration> tag as are needed to define the namespace. In addition, following each <Database> tag, you can add <GlobalMapping>, <RoutineMapping>, and <ClassMapping> tags as required. The </Configuration> tag activates the defined mappings.
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.
For an example, see Example later in this chapter.
Adding Users and Passwords
There are several ways to add users (including their roles and passwords) to the installed instance, as follows:
Adding Messages
You can define log messages to be displayed by incorporating <Log> tags in your class, in the following format:
<Log Level="<N>" 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 is equal to or greater than the value you specify, the message is logged. The text is limited to 32,000 characters.
You set the 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:
ClassMethod setup(ByRef pVars, pLogLevel As %Integer = 3, 
   pInstaller As %Installer.Installer, 
   pLogger As %Installer.AbstractLogger) 
   As %Status [ CodeMode = objectgenerator, Internal ]
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:
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:
Values shown in italics are the defaults used if the setting is not specified explicitly.
<ClassMapping>
Optional; within <Configuration>. Defines package mapping for the namespace. For example:
<ClassMapping Package="MYAPP"
     From="MYAPP"/>
<Compile>
Optional; within <Namespace>. Defines a class name to be compiled. For example:
<Compile  
    Class=""
    Flags="ck"
    IgnoreErrors="0"/>
<Configuration>
Required if databases and/or mappings are being defined; within <Namespace>. Contains namespace configuration tags for databases and mapping. For example:
<Configuration> 
    <Database . . . />
</Configuration>
The closing tag (</Configuration> activates the mappings for the databases in a namespace to update the .cpf file.
<CopyClass>
Optional; within <Namespace>. Defines a class to be copied from a source to a target. For example:
<CopyClass  
    Src="MyPackage.MyClass"
    Target="NewPackage.NewClass"
    Replace="0"/>
<CopyDir>
Optional; within <Manifest>. Defines a directory to be copied from a source to a target. For example:
<CopyDir  
    Src="${MGRDIR}"
    Target="F:\MyTargetDir"
    IgnoreErrors="0"/>
<CopyFile>
Optional; within <Manifest>. Defines a file to be copied from a source to a target. For example:
<CopyFile  
    Src="${MGRDIR}/cconsole.log"
    Target="F:\CacheLogFiles\base_cconsole.log"
    IgnoreErrors="0"/>
<CSPApplication>
Optional; within <Namespace>. Defines one or more CSP applications; the supported authentication flags are 4 (Kerberos), 32 (Password), and 64 (Unauthenticated). For example:
<CSPApplication 
    Url="/csp/foo/bar"
    Description=""
    Directory="C\InterSystems\Cache\CSP\Democode1"
    Resource=""
    Grant="%DB_%DEFAULT"
    Recurse="true"
    LoginClass=""
    CookiePath="/csp/demo1"
    AuthenticationMethods="64"/>
<Database>
Required; within <Configuration>. Defines one or more databases used in the namespace. For example:
<Database Name="${NAMESPACE}" 
    Dir="${MGRDIR}/${NAMESPACE}"  
    Create="yes"
    Resource="${DBRESOURCE}"
    Blocksize="8192"
    ClusterMountMode="0"
    Collation="5"
    Encrypted="0"
    EncryptionKeyID=
    ExpansionSize="0"
    InitialSize="1"
    MaximumSize="0"
    MountAtStartup="0"
    MountRequired="0"
    StreamLocation=
    PublicPermissions=""/>
<Database Name="MYAPP" 
    Dir="${MYAPPDIR}/db"  
    Create="no"
    Resource="${MYAPPRESOURCE}"
    Blocksize="8192"
    ClusterMountMode="0"
    Collation="5"
    Encrypted="0"
    EncryptionKeyID=
    ExpansionSize="0"
    InitialSize="1"
    MaximumSize="0"
    MountAtStartup="0"
    MountRequired="0"
    StreamLocation=
    PublicPermissions=""/>
<ForEach>
Optional; within <Manifest>. Defines values for each iteration of the specified index key. For example:
<ForEach 
    Index="TargetNS"
    Values="%SYS,Samples,User">
    <!--Code for each iteration of TargetNS through the values-->
</ForEach>
<GlobalMapping>
Optional; within <Configuration>. Defines global mapping for the namespace; optional Collation specification defaults to Caché standard. For example:
<GlobalMapping Global="MyAppData.*"
    From="MYAPP" Collation="30"/> 
<GlobalMapping Global="cspRule" 
    From="MYAPP"/>
<If>
Optional; within <Manifest> or <Namespace>. Defines conditional. For example:
<If Condition='$L("${NAMESPACE}")=0'>
    <Error Status="$$$NamespaceDoesNotExist">
        <Arg Value="${NAMESPACE}"/>
    </Error>
</If>
<Import>
Optional; within <Namespace>. Defines globals, routines, and packages to be loaded (and routines and packages to be compiled). For example:
<Import File="${MYAPPDIR}/data/Defaults.gof"/ 
    Flags="ck"
    IgnoreErrors="0"/>
<Invoke>
Optional; within <Namespace>. Defines class methods to execute routines and access globals that have been imported. For example:
<Invoke Class="Sample.Installer" Method="SetupDefaults" CheckStatus="1" Return="RetVal"> 
    <Arg Value="${NAMESPACE}"/>
    <Arg Value="${ISUPGRADE}"/>
</Invoke>
"RetVal" can then be used as a variable (${RetVal}).
<Log>
Optional; within <Manifest> or <Namespace>. Defines a log message and the log level when it is displayed. For example:
<Log
     Level="3" 
     Text="Create mappings"/>
<Manifest>
Required. Contains the installation instructions (all other tags). For example:
<Manifest>
    <Namespace ... >
        <Configuration>
        </Configuration>
    </Namespace>
</Manifest>
<Namespace>
Required; within <Manifest>. One for each namespace. For example:
<Namespace Name="${NAMESPACE}" 
     Create="yes" 
     Code="${NAMESPACE}"
     Data="${NAMESPACE}"> 
          <Configuration> 
               <Database . . . />
          </Configuration>
</Namespace>
<Resource>
Optional; within <Manifest>. Defines a resource. For example:
<Resource 
    Description="Accounting"
    Permission="RW"
    Target="USER"/>
<Role>
Optional; within <Manifest>. Defines a role. For example:
<Role 
    Name="%DB_USER"
    Description=
    Resources="MyResource:RW,MyResource1:RWU"
    RolesGranted=/>
<RoutineMapping>
Optional; within <Configuration>. Defines routine mapping for the namespace. For example:
<RoutineMapping 
    Routines="MYAPP"
    Type="INC"
    From="MYAPP"/> 
Important:
Do not use a wildcard in the Routines value when Type=INC, as such mappings are not indexed and therefore not visible in the Management Portal and Studio.
<SystemSetting>
Optional; within <Manifest>. Sets any Config class that implements the Modify method. For example:
<SystemSetting 
    Name="Config.Miscellaneous.EnableLongStrings"
    Value="1"/>
<User>
Optional; within <Manifest>. Defines a user; if PasswordVar is specified, the user password must be provided in the referenced variable name. For example:
<User 
    Username="Clerk1"
    PasswordVar="clerk1pw"
    Roles="Dataentry"
    Fullname="Data Entry Clerk"
    Namespace=
    Routine=
    ExpirationDate=
    ChangePassword=
    Enabled=
    Comment=""/>
<Var>
Optional; within <Manifest>. Defines variables that can be used with the manifest. For example:
<Var Name="Namespace" Value="MUSIC"/> 
<Var Name="GlobalDatabase" Value="${Namespace}G"/> 
<Var Name="RoutineDatabase" Value="${Namespace}R"/> 
<Var Name="AppDir" Value="C:\MyApp\${CFGNAME}"/> 
<Var Name="GlobalDatabaseDir" Value="${AppDir}\${GlobalDatabase}"/> 
<Var Name="RoutineDatabaseDir" Value="${AppDir}\${RoutineDatabase}"/> 
<Var Name="Resource" Value="%DB_${Namespace}"/> 
<Var Name="Role" Value="${Namespace}"/> 
<Var Name="CSPResource" Value="CSP_${Namespace}"/> 
For a comprehensive example of a user-defined installer class, see Sample.Installer in the SAMPLES namespace.
For an up-to-date list of tags and attributes, see the %Installer class reference documentation.
Variables Available within <Manifest>
The following table lists the predefined variables that you can use in the manifest:
Variable Name Description
SourceDir (Available only when the installer is run) Directory from which the installation (setup_cache.exe or cinstall) is running.
ISCUpgrade (Available only when the installer is run) Indicates whether this is a new installation or an upgrade. This variable is either 0 (new installation) or 1 (upgrade).
CFGDIR See INSTALLDIR.
CFGNAME Instance name.
CPUCOUNT Number of operating system CPUs.
CSPDIR CSP directory.
HOSTNAME Name of the host server.
HTTPPORT Web server port.
INSTALLDIR Directory into which Caché is installed.
MGRDIR Manager (mgr) directory.
PLATFORM Operating system.
PORT Caché superserver port.
PROCESSOR Processor chip.
VERSION Caché version number.
Using the Manifest
You can use the manifest as follows:
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.
Note:
For a more comprehensive example, see Sample.Installer in the SAMPLES namespace.
Include %occInclude

/// Simple example of installation instructions (Manifest)
Class MyInstallerPackage.SimpleManifest
{

XData SimpleManifest [ XMLNamespace = INSTALLER ]
{
<Manifest>
    <Namespace Name="MyNamespace" Create="yes" 
        Code="MyRoutinesDB" Data="MyDataDB">
      <Configuration>
        <Database Name="MyRoutinesDB" Create="yes" 
            Dir="C:\MyInstallerDir\MyRoutinesDB"/>
        <Database Name="MyDataDB" Create="yes" 
            Dir="C:\MyInstallerDir\MyDataDB"/>
        <Database Name="MyMappingDB" Create="yes" 
            Dir="C:\MyInstallerDir\MyMappingDB"/>
        <GlobalMapping Global="t*" From="MyMappingDB"/>
      </Configuration>
    </Namespace>
</Manifest>
}

/// This is a method generator whose code is generated by XGL.
ClassMethod setup(ByRef pVars, pLogLevel As %Integer = 3, 
   pInstaller As %Installer.Installer, 
   pLogger As %Installer.AbstractLogger) 
   As %Status [ CodeMode = objectgenerator, Internal ]
{
    #; Let our XGL document generate code for this method. 
    Quit ##class(%Installer.Manifest).%Generate(%compiledclass, 
    %code, "SimpleManifest")
}

}
After the class is compiled, you can invoke it in the Caché Terminal as shown below (assuming you created the class in the USER namespace):
%SYS> znspace "USER"
USER> do ##class(MyInstallerPackage.SimpleManifest).setup()