Using the Caché %Installer Class - InterSystems Documentation

Using the Caché %InstallerClassVersion 2010.225 April 2011InterSystems Corporation 1 Memorial Drive Cambridge MA 02142 www.intersystems.com

Using the Caché %Installer ClassCaché Version 2010.2 25 April 2011Copyright © 2011 InterSystems CorporationAll rights reserved.This book was assembled and formatted in Adobe Page Description Format (PDF) using tools and information from the following sources:Sun Microsystems, RenderX, Inc., Adobe Systems, and the World Wide Web Consortium at www.w3c.org.The primary document developmenttools were special-purpose XML-processing applications built by InterSystems using Caché and Java.andCaché WEBLINK, Distributed Cache Protocol, M/SQL, M/NET, and M/PACT are registered trademarks of InterSystems Corporation., , andInterSystems Jalapeño Technology, Enterprise Cache Protocol, ECP, and InterSystems Zen are trademarks of InterSystems Corporation.All other brand or product names used herein are trademarks or registered trademarks of their respective companies or organizations.This document contains trade secret and confidential information which is the property of InterSystems Corporation, One Memorial Drive,Cambridge, MA 02142, or its affiliates, and is furnished for the sole purpose of the operation and maintenance of the products of InterSystemsCorporation. No part of this publication is to be used for any other purpose, and this publication is not to be reproduced, copied, disclosed,transmitted, stored in a retrieval system or translated into any human or computer language, in any form, by any means, in whole or in part,without the express prior written consent of InterSystems Corporation.The copying, use and disposition of this document and the software programs described herein is prohibited except to the limited extentset forth in the standard software license agreement(s) of InterSystems Corporation covering such programs and related documentation.InterSystems Corporation makes no representations and warranties concerning such software programs other than those set forth in suchstandard software license agreement(s). In addition, the liability of InterSystems Corporation for any losses or damages relating to or arisingout of the use of such software programs is limited in the manner set forth in such standard software license agreement(s).THE FOREGOING IS A GENERAL SUMMARY OF THE RESTRICTIONS AND LIMITATIONS IMPOSED BY INTERSYSTEMSCORPORATION ON THE USE OF, AND LIABILITY ARISING FROM, ITS COMPUTER SOFTWARE. FOR COMPLETE INFORMATIONREFERENCE SHOULD BE MADE TO THE STANDARD SOFTWARE LICENSE AGREEMENT(S) OF INTERSYSTEMS CORPORATION,COPIES OF WHICH WILL BE MADE AVAILABLE UPON REQUEST.InterSystems Corporation disclaims responsibility for errors which may appear in this document, and it reserves the right, in its sole discretionand without notice, to make substitutions and modifications in the products and practices described in this document.For Support questions about any InterSystems products, contact:InterSystems Worldwide Customer SupportTel: +1 617 621-0700Fax: +1 617 374-9391Email: support@InterSystems.com

Using the Caché %Installer Class%Installer is a class that lets you define an installation manifest that describes a resulting configuration. Instead of defininga step-by-step process, %Installer defines the finished configuration. Use XML tags to define the installation manifest,which generates code to configure the instance; in addition, parameters can be passed to further control execution. The%Installer manifest can be invoked automatically during installation, from a terminal session (in the %SYS namespace), orwithin code.This article provides information about defining namespaces, databases, and mappings (global, routine, and package).Classes, routines, and globals can be loaded into a namespace defined in the installation manifest; then %Installer cancompile the classes and routines making them available for execution in the namespace in which they are loaded. It includesthe following topics:• Using the %Installer Class• Adding Users and Passwords• %Installer Tags• Invoking the %Installer Class Methods• Example of User-created %Installer Class1 Using the %Installer ClassThe following example illustrates the structure of an %Installer class:Include %occIncludeClass MyPackage.MyInstaller{XData MyInstall [ XMLNamespace = INSTALLER ]{

Adding Users and Passwords}}ClassMethod setup(ByRef pVars, pLogLevel As %Integer, pInstaller As%Installer.Installer) As %Status [ CodeMode = objectgenerator,Internal ]{#; Let XGL document generate code for this method.Quit ##class(%Installer.Manifest).%Generate(%compiledclass,%code, "MyInstall")}Important:The %occInclude include file, which includes methods required by the %Installer class, must be specifiedat the beginning of every %Installer class you create.The name of the XData block (MyInstall) is used by the MyPackage.MyInstaller.setup method to generate the code forthat manifest, which is passed as the third argument of the %Installer.Manifest.%Generate() method.Note:Referencing XMLNamespace = INSTALLER provides Studio Assist capability while authoring your %Installerclass.The outer-most xml tag, , contains all the information for code generation. There can be as many tags as needed within the tag to define namespaces in the manifest.A tag, which is located inside a tag, is required only if databases and/or mappingsare being defined. There must be as many tags within the tag as are needed to definethe namespace. In addition, following each tag, you can add , ,and tags as required. The tag activates the defined mappings.Within the context of a tag — after the databases and their mappings have been defined — globals can beloaded, and routines and classes can be loaded and compiled using tag. Class methods can be invoked usingthe tag. Invoked class methods can execute routines and access globals that have been imported.Optionally, you can define variable pairs with the tag; each variable must specify a name and value. When the valuefor the is needed, the name is referenced by the ${NameAssigned} syntax.2 Adding Users and PasswordsYou can add users (including their roles and passwords) with the System Management Portal, or you can use the Security.Usersclass on a staging instance of Caché or Ensemble as follows:1. Export the user information by using the Security.Users.Export() method.2. Import the user information by adding the following at the beginning of your %Installer class (in the %SYS namespace):where PathToExportedUserInformation is the location of the output file specified in the Security.Users.Export()method.3 %Installer TagsFollowing are descriptions of the tags (in alphabetical order) you can use in your %Installer class.Note:Values shown in italics are the defaults used if the setting is not specified explicitly.2 Using the Caché %Installer Class

%Installer TagsOptional; within . Defines package mapping for the namespace. For example:Optional; within . Defines a class name to be compiled. For example:Required; within . Contains namespace configuration tags for databases and mapping. For example:The closing tag ( activates the mappings for the databases in a namespace to update the .cpffile.Optional; within . Defines a class to be copied from a source to a target. For example:Optional; within . Defines a directory to be copied from a source to a target. For example:Optional; within . Defines a file to be copied from a source to a target. For example:Optional; within . Defines one or more CSP applications; the supported authentication flags are 4(Kerberos), 32 (Password), and 64 (Unauthenticated). For example:Using the Caché %Installer Class 3

%Installer TagsRequired; within . Defines one or more databases used in the namespace. For example:Optional; within . Defines values for each iteration of the specified index key. For example:

%Installer TagsOptional; within . Defines class methods to execute routines and access globals that have beenimported. For example:"RetVal" can then be used as a variable (${RetVal}).Required. Contains the installation instructions (all other tags). For example:Required; within . One for each namespace. For example:Optional; within . Defines a role. For example:Optional; within . Defines routine mapping for the namespace. For example:Optional; within . Sets any Config class that implements the Modify method. For example:Optional; within . Defines a user; if PasswordVar is specified, the user password must be providedin the referenced variable name. For example:Using the Caché %Installer Class 5

Invoking the %Installer Class MethodsOptional; within . Defines variables that can be used with the manifest. For example: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 documentation.4 Invoking the %Installer Class MethodsYou can invoke the %Installer class as follows:• In the %SYS namespace, enter the following command in the Caché Terminal:%SYS> Do ##class(MyPackage.MyInstaller).setup()You can pass an array by reference to the setup() method where the subscript is used as a variable in the and the node value is the variable . For example:%SYS> Set vars("SourceDir")="c:\myinstaller"%SYS> Set vars("Updated")="Yes"%SYS> Do ##class(MyPackage.MyInstaller).setup(.vars,3)where the second parameter (3) is the log level.• Export the %Installer class as DefaultInstallerClass.xml to the same directory where the Caché install (either.msi, setup_cache.exe, or cinstall) is run. It is imported into %SYS, compiled, and the setup() method is executed.Note:If you use the export technique, you cannot pass arguments to the setup() method.On Microsoft Windows systems, you can modify the .msi install package to pass variable pairs to the setup()method. Alternatively, you can use command-line arguments to pass the location of the exported %Installerclass and variables, as shown in the following example:setup_cache.exe INSTALLERMANIFEST="c:\MyStuff\MyInstaller.xml"INSTALLERMANIFESTPARAMS="SourceDir=c:\mysourcedir,Updated=Yes"On UNIX®/Linux systems, set environment variables to define the location of the exported %Installer classand variable pairss, as shown in the following example:ISC_INSTALLER_MANIFEST=c:\MyStuff\MyInstaller.xmlISC_INSTALLER_PARAMETERS=SourceDir=c:\mysourcedir,Updated=Yescinstall6 Using the Caché %Installer Class

Example of User-created %Installer Class5 Example of User-created %Installer ClassThe following class creates a namespace (MyNamespace) and three databases; two of the databases are defined as thedefault databases for globals (MyDataDB) and routines (MyRoutinesDB), while the third database (MyMappingDB) is aglobals database that overrides the default database mapping for t* globals in the MyNamespace namespace.Note:For a more comprehensive example of a user-defined installer class, see Sample.Installer in the SAMPLESnamespace.Include %occInclude/// Simple example of installation instructions (Manifest)Class MyInstallerPackage.SimpleManifest{XData SimpleManifest [ XMLNamespace = INSTALLER ]{}/// This is a method generator whose code is generated by XGL.ClassMethod setup(ByRef pVars, pLogLevel As %Integer,pInstaller As %Installer.Installer) 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 inthe USER namespace):%SYS> znspace "USER"USER> do ##class(MyInstallerPackage.SimpleManifest).setup()Using the Caché %Installer Class 7