Deploying Applications in InterSystems Caché

Introduction

So, you have developed your application on InterSystems technologies. Now it must be deployed at the client and often more than once. During the development process, you got an installation manual - because it is not enough just to import the classes, you also need to fine-tune the ~~system with a file and~~ fine-tune the environment for your needs.

To solve these problems there is a utility % Installer . This article is about her.

% Installer

This utility allows you to define an installation manifest that describes the target Caché configuration, rather than steps to achieve it. You describe what should be, and Caché will already generate all the necessary code. You distribute, respectively, only the manifest itself, code generation occurs already in place within a specific Caché server.

To write a manifest, you create an XData block with a description of the desired configuration, as well as a method that generates COS code based on the XData block (it is always the same). Once you have written the manifest, you can call it during the installation of Caché, from a terminal or COS-code. The manifest should be executed in the% SYS area. The manifest is available as system parameters (super-port, OS, mgr directory, etc.), as well as arbitrary parameters passed by the user. Therefore, the installer class must meet the following requirements:
')

Include link to %occInclude.inc ;
Contain an XData block with a Caché server configuration;
A block can be called with any valid name.
Add [XMLNamespace = INSTALLER] after the block name to include hints in the studio;
Root element (there can be only one) -
```
 <Manifest> 
```
all other elements are located inside it;
You must define a setup() method that performs code generation from an XData block.

Using

A ready installation manifest can be launched in several ways :

In the area of% SYS from the terminal or COS code
```
 do ##class(MyPackage.MyInstaller).setup() 
```
Automatically when installing Caché. To do this, export the installer class to the DefaultInstallerClass.xml file in the folder with the Caché distribution (where setup_cache.exe, or cinstall is located). When installing Caché, it will be imported into the% SYS area and launched (via the setup () method)

Example

Consider a simple example. Create an App.Installer class with an installer that creates an area with the name given by the user:

App.Installer

Include % occInclude
Class App.Installer
{
/// The generated code can be viewed in zsetup + 1 ^ App.Installer.1
XData Install [ XMLNamespace = INSTALLER]
{
< Manifest >
< If Condition = '(## class (Config. Namespaces) .Exists ("$ {Namespace}") = 0)' >
< Log Text = "Creating namespace $ {Namespace}" Level = "0" />
< Namespace Name = "$ {Namespace}" Create = "yes" Code = "$ {Namespace}" Ensemble = "0" Data = "$ {Namespace}" >
< Configuration >
< Database Name = "$ {Namespace}" Dir = "$ {MGRDIR} / $ {Namespace}" Create = "yes" />
</ Configuration >
</ Namespace >
< Log Text = "End Creating namespace $ {Namespace}" Level = "0" />
</ If >
</ Manifest >
}
/// Method that is called to perform the installation.
/// During class compilation, COS code is generated
/// After that, the installer starts with the parameters as follows:
/// Set pVars ("Namespace") = "TempNamespace"
/// Do ## class (App.Installer) .setup (.pVars)
ClassMethod setup ( ByRef pVars , pLogLevel As% Integer = 0 , pInstaller As% Installer.Installer ) As% Status [ CodeMode = objectgenerator, Internal ]
{
Quit ## class ( % Installer.Manifest ). % Generate ( % compiledclass , % code , "Install" )
}
}

In this example, the following happens:

Check whether there is a region with a name equal to the value of the Namespace variable (for example, the value is NewNamespace);
If not, then the fact of the beginning of the creation of the NewNamespace area is logged;
Definition of area:
- C name NewNamespace;
- The area needs to be created;
- DB code NewNamespace;
- Ensemble do not turn on;
- Database NewNamespace.
Database creation
- C name NewNamespace;
- In the folder mgr / NewNamespace (note that the variable MGRDIR is available to us by default).
Write to the log the completion of the creation area.

To run from the terminal, execute the following commands:

Set pVars ( "Namespace" ) = "NewNamespace"
Do ## class ( App.Installer ). setup (. pVars )

What will bring

2015-10-16 16:26:18 0 App.Installer: Installation starting at 2015-10-16 16:26:18, LogLevel = 0
2015-10-16 16:26:18 0: Creating namespace NewNamespace
2015-10-16 16:26:19 0: End Creating namespace NewNamespace
2015-10-16 16:26:19 0 App.Installer: Installation succeeded at 2015-10-16 16:26:19
2015-10-16 16:26:19 0% Installer: Elapsed time .605257s

List of items

The manifesto is formed from the following elements:

Element	Parent element	Attributes (default)	Description
Arg	Invoke, error	Value - the value of the argument	Pass an argument to a method called via Invoke or Error
Classmapping	Configuration	Package - package for display From - the name of the database from which we display	Creates a mapping of classes from a database into a box, inside the Configuration element of which we are
Compile	Namespace	Class - the name of the class (s) to compile Flags - compilation flags (ck) IgnoreErrors - ignore errors (0)	Compiles classes. Calls $ System.OBJ.Compile (Class, Flags)
Configuration	Namespace		Required to create an area and database. The closing tag activates the mappings and updates the cpf file.
Copyclass	Namespace	Src - source class Target - target class Replace - delete the original class (0)	Copies or moves the source class to the target.
Copydir	Manifest	Src - source directory Targe - target directory IgnoreErrors - ignore errors (0)	Copy directory
Copyfile	Manifest	Src - source file Targe - target file IgnoreErrors - ignore errors (0)	Copy file
Credential	Production	Name - the name of the access details Username - username Password - password Overwrite - override in case of existence	Creates or redefines access credentials.
CSPApplication	Namespace	AuthenticationMethods - Authentication Methods Available AutoCompile - autocompile CSPZENEnabled - CSP / ZEN flag ChangePasswordPage - password change page CookiePath - path for session cookie CustomErrorPage - custom error page DefaultSuperclass - the default super class DefaultTimeout - session timeout Description - Description Directory - path to CSP-files EventClass - event class Grant - a list of roles that are issued at the entrance GroupById - group by id InboundWebServicesEnabled - inbound web services IsNamespaceDefault - application for default domain LockCSPName - lock on CSP name LoginClass - login page PackageName - package name PermittedClasses - Permitted Classes Recurse - subdirectories (0) Resource - required resource ServeFiles - service files ServeFilesTimeout - timeout for service files TwoFactorEnabled - two-factor authentication Url - the name of the web application UseSessionCookie - use session cookie	Creates or modifies a web application. Detailed description of the settings in the documentation and class Security.Applications
Database	Configuration	BlockSize - block size ClusterMountMode - mount the database as part of a cluster Collation - sorting Create - create a database - yes, no, overwrite (yes) Dir - directory Encrypted - encrypt EncryptionKeyID - Encryption Key ID ExpansionSize - extension InitialSize - the initial size MaximumSize - the minimum size MountAtStartup - mount at startup MountRequired - mount required Name - the name PublicPermissions - public rights Resource - resource StreamLocation - stream location	Creates or modifies a database. Detailed description of the settings in the documentation and class Config.Databases
Default	Manifest	Name - variable name Value - the value of the variable Dir - the value of the variable, if it is the path to the folder / file	Defines the value of a variable if it is not defined.
Else	Manifest, Namespace		Executed if the if-condition check is negative
Error	Manifest	Status - error code Source - the source of the error	Throws an exception. $ {} and # {} syntax not available
ForEach	Manifest	Index - variable name Values - a list of variable values	Shared Cycle Operator
GlobalMapping	Configuration	Global - global name From - the database name from which we display Collation - sorting (Caché Standard)	Displays the global
If	Manifest, Namespace	Condition	Conditional operator
IfDef	Manifest, Namespace	Var - variable name	The conditional operator, if the variable is defined
IfNotDef	Manifest, Namespace	Var - variable name	The conditional operator, in case the variable is not defined
Import	Namespace	File - file / folder for import Flags - compilation flags (ck) IgnoreErrors - ignore errors (0) Recurse - recursive import (0)	Import files. Causes: $ System.OBJ.ImportDir (File ,, Flags ,, Recurse) and $ System.OBJ.Load (File, Flags)
Invoke	Namespace	Class - class Method - method CheckStatus - check returned status Return - write the result to the variable	Calls a class method, you can pass arguments and get the result of the execution.
Loadpage	Namespace	Name - the path to the CSP page Dir - folder with CSP pages Flags - compilation flags (ck) IgnoreErrors - ignore errors (0)	Loads CSP files via $ System.CSP.LoadPage (Name, Flags) and $ System.CSP.LoadPageDir (Dir, Flags)
Log	Manifest	Level - logging level from 0 (minimum) to 3 (detailed) Text - text, up to 32000 characters	Adds a message to the log if the logging level is greater than or equal to the level attribute
Manifest			Root element The only one in the manifest, all other elements are located inside it.
Namespace	Manifest	Name - the name of the area reate - create region - yes, no, overwrite (yes) Code - DB with code Data - database with data Ensemble - enable Ensemble in the field Other attributes are associated with Ensemble web applications.	Defines the scope of the installer
Production	Namespace	Name - product name AutoStart - automatic product launch	Customizes Ensemble products
Resource	Manifest	Name - the name of the resource Description - Description Permission - public rights	Creates or modifies a resource.
Role	Manifest	Name - the name of the role Description - Description Resources - resources in the form of "MyResource: RW, MyResource1: RWU" RolesGranted - give related roles	Creates a role
RoutineMapping	Configuration	Routines - the name of the routine (s) Type - one of the types "MAC, INT, INC, OBJ, ALL" From - from which database	Creates a mapping routine
Setting	Production	Item - custom item Target - setting type: Item, Host, Adapter Setting - the name of the setting Value - setting value	Configures an Ensemble product item. Calls the Ens.Production method : ApplySettings
Systemsetting	Manifest	Name - class.property of package Config Value - property value	Sets the value of the Config package properties (via the Modify method)
User	Manifest	Username - username PasswordVar - variable containing the password Roles - list of user roles Fullname - full name Namespace - starting area Routine - starting routine ExpirationDate - the date after which the user will no longer be activated ChangePassword - change password at next login Enabled - whether the user is activated	Creates or modifies user
Var	Manifest	Name - variable name Value - the value of the variable	Defines the value of a variable.

Variables

Variables can act as attribute values; they are defined in one of three ways:

$ {<Variable_Name>} - during the execution of the manifest, the value of the variable is calculated (transmitted by the user or one of the environment variables, see below);
$ {# <ParameterName>} - during compilation are replaced with the value of the specified parameter of the installer class;
# {<COS_code>} - during the execution of the manifest, the value of the specified COS expression is calculated. Do not forget about quotes.

Parameter values are determined at compile time, so they can be part of a variable or COS expression. Interpretation of variables occurs before the interpretation of the COS-code, so variables can be included in the COS-expression, for example: #{$ZCVT("${NAMESPACE}","L")}.

Environment Variables

The following variables are always available:

Variable	Description	Example value
Sourcedir	(Only when installing Cache) Directory where the installer is located (setup_cache.exe or cinstall)	/ InterSystems / distr /
ISCUpgrade	(Only when installing Cache) Determines if it is installed or updated	0 (installation) 1 (update)
CFGDIR	See INSTALLDIR.	/ InterSystems / Cache /
CFGFILE	Cpf file path	/InterSystems/Cache/cache.cpf
CFGNAME	Instance name	CACHE
CPUCOUNT	CPU core number	four
CSPDIR	CSP Directory	/ InterSystems / Cache / csp /
HOSTNAME	Web server name	SCHOOL15
HTTPPORT	Web server port	80
INSTALLDIR	Directory where Caché is installed	/ InterSystems / Cache /
MGRDIR	Management Directory (mgr)	/ InterSystems / Cache / mgr /
PLATFORM	operating system	UNIX
PORT	Port superserver Caché	1972
PROCESSOR	Platform name	x86-64
VERSION	Caché Version	2015.1.1

Debugging

It is not clear what values attributes can take. For clarification, look at the generated setup method int code. Typically, the main call is the method:

tInstaller.ElementName() ,

those. % Installer.Installer class method that already calls system methods directly. Alternatively, you can look at the

%Installer., . %OnBeforeGenerateCode, %OnGenerateCode, %OnAfterGenerateCode.

, . TSTART / TROLLBACK , Caché ( Caché , ).


MDX2JSON . installer.xml MDX2JSON.Installer. .

:

do ##class(MDX2JSON.Installer).setup()
GitHub-, « » MDX2JSON MDX2JSON, MDX2SJON %All, REST- /MDX2JSON , .


.
Sample.Installer Samples.
CacheGitHubCI .
SYSMON Dashboards .
DeepSee Audit .


%Installer InterSystems Caché Ensemble.

class code

%Installer., . %OnBeforeGenerateCode, %OnGenerateCode, %OnAfterGenerateCode.

, . TSTART / TROLLBACK , Caché ( Caché , ).


MDX2JSON . installer.xml MDX2JSON.Installer. .

:

do ##class(MDX2JSON.Installer).setup()
GitHub-, « » MDX2JSON MDX2JSON, MDX2SJON %All, REST- /MDX2JSON , .


.
Sample.Installer Samples.
CacheGitHubCI .
SYSMON Dashboards .
DeepSee Audit .


%Installer InterSystems Caché Ensemble.

%Installer., . %OnBeforeGenerateCode, %OnGenerateCode, %OnAfterGenerateCode.

, . TSTART / TROLLBACK , Caché ( Caché , ).


MDX2JSON . installer.xml MDX2JSON.Installer. .

:

do ##class(MDX2JSON.Installer).setup()
GitHub-, « » MDX2JSON MDX2JSON, MDX2SJON %All, REST- /MDX2JSON , .


.
Sample.Installer Samples.
CacheGitHubCI .
SYSMON Dashboards .
DeepSee Audit .


%Installer InterSystems Caché Ensemble.

`%Installer., . %OnBeforeGenerateCode, %OnGenerateCode, %OnAfterGenerateCode. , . TSTART / TROLLBACK , Caché ( Caché , ). MDX2JSON . installer.xml MDX2JSON.Installer. . : do ##class(MDX2JSON.Installer).setup() GitHub-, « » MDX2JSON MDX2JSON, MDX2SJON %All, REST- /MDX2JSON , . . Sample.Installer Samples. CacheGitHubCI . SYSMON Dashboards . DeepSee Audit . %Installer InterSystems Caché Ensemble.`

%Installer., . %OnBeforeGenerateCode, %OnGenerateCode, %OnAfterGenerateCode.

, . TSTART / TROLLBACK , Caché ( Caché , ).


MDX2JSON . installer.xml MDX2JSON.Installer. .

:

do ##class(MDX2JSON.Installer).setup()
GitHub-, « » MDX2JSON MDX2JSON, MDX2SJON %All, REST- /MDX2JSON , .


.
Sample.Installer Samples.
CacheGitHubCI .
SYSMON Dashboards .
DeepSee Audit .


%Installer InterSystems Caché Ensemble.

 %Installer.,      .     %OnBeforeGenerateCode, %OnGenerateCode, %OnAfterGenerateCode. 
 
   ,      .     TSTART / TROLLBACK     ,   Caché (  Caché ,       ). 
 
   
  MDX2JSON   .         installer.xml   MDX2JSON.Installer.            . 
 
    : 
 
 do ##class(MDX2JSON.Installer).setup() 
       GitHub-,  « »   MDX2JSON    MDX2JSON,   MDX2SJON  %All,  REST- /MDX2JSON   ,      . 
 
   
    . 
  Sample.Installer   Samples. 
  CacheGitHubCI   . 
  SYSMON Dashboards   . 
  DeepSee Audit   . 
 
  
  %Installer       InterSystems Caché  Ensemble.

%Installer., . %OnBeforeGenerateCode, %OnGenerateCode, %OnAfterGenerateCode.

, . TSTART / TROLLBACK , Caché ( Caché , ).


MDX2JSON . installer.xml MDX2JSON.Installer. .

:

do ##class(MDX2JSON.Installer).setup()
GitHub-, « » MDX2JSON MDX2JSON, MDX2SJON %All, REST- /MDX2JSON , .


.
Sample.Installer Samples.
CacheGitHubCI .
SYSMON Dashboards .
DeepSee Audit .


%Installer InterSystems Caché Ensemble.

`%Installer., . %OnBeforeGenerateCode, %OnGenerateCode, %OnAfterGenerateCode. , . TSTART / TROLLBACK , Caché ( Caché , ). MDX2JSON . installer.xml MDX2JSON.Installer. . : do ##class(MDX2JSON.Installer).setup() GitHub-, « » MDX2JSON MDX2JSON, MDX2SJON %All, REST- /MDX2JSON , . . Sample.Installer Samples. CacheGitHubCI . SYSMON Dashboards . DeepSee Audit . %Installer InterSystems Caché Ensemble.`

%Installer., . %OnBeforeGenerateCode, %OnGenerateCode, %OnAfterGenerateCode.

, . TSTART / TROLLBACK , Caché ( Caché , ).


MDX2JSON . installer.xml MDX2JSON.Installer. .

:

do ##class(MDX2JSON.Installer).setup()
GitHub-, « » MDX2JSON MDX2JSON, MDX2SJON %All, REST- /MDX2JSON , .


.
Sample.Installer Samples.
CacheGitHubCI .
SYSMON Dashboards .
DeepSee Audit .


%Installer InterSystems Caché Ensemble.

`%Installer., . %OnBeforeGenerateCode, %OnGenerateCode, %OnAfterGenerateCode. , . TSTART / TROLLBACK , Caché ( Caché , ). MDX2JSON . installer.xml MDX2JSON.Installer. . : do ##class(MDX2JSON.Installer).setup() GitHub-, « » MDX2JSON MDX2JSON, MDX2SJON %All, REST- /MDX2JSON , . . Sample.Installer Samples. CacheGitHubCI . SYSMON Dashboards . DeepSee Audit . %Installer InterSystems Caché Ensemble.`

%Installer., . %OnBeforeGenerateCode, %OnGenerateCode, %OnAfterGenerateCode.

, . TSTART / TROLLBACK , Caché ( Caché , ).


MDX2JSON . installer.xml MDX2JSON.Installer. .

:

do ##class(MDX2JSON.Installer).setup()
GitHub-, « » MDX2JSON MDX2JSON, MDX2SJON %All, REST- /MDX2JSON , .


.
Sample.Installer Samples.
CacheGitHubCI .
SYSMON Dashboards .
DeepSee Audit .


%Installer InterSystems Caché Ensemble.

`%Installer., . %OnBeforeGenerateCode, %OnGenerateCode, %OnAfterGenerateCode. , . TSTART / TROLLBACK , Caché ( Caché , ). MDX2JSON . installer.xml MDX2JSON.Installer. . : do ##class(MDX2JSON.Installer).setup() GitHub-, « » MDX2JSON MDX2JSON, MDX2SJON %All, REST- /MDX2JSON , . . Sample.Installer Samples. CacheGitHubCI . SYSMON Dashboards . DeepSee Audit . %Installer InterSystems Caché Ensemble.`

%Installer., . %OnBeforeGenerateCode, %OnGenerateCode, %OnAfterGenerateCode.

, . TSTART / TROLLBACK , Caché ( Caché , ).


MDX2JSON . installer.xml MDX2JSON.Installer. .

:

do ##class(MDX2JSON.Installer).setup()
GitHub-, « » MDX2JSON MDX2JSON, MDX2SJON %All, REST- /MDX2JSON , .


.
Sample.Installer Samples.
CacheGitHubCI .
SYSMON Dashboards .
DeepSee Audit .


%Installer InterSystems Caché Ensemble.

Source: https://habr.com/ru/post/268767/

All Articles

Deploying Applications in InterSystems Caché

Introduction

% Installer

Using

Example

List of items

Variables

Environment Variables

Debugging

More articles: