インストール・マニフェストの作成および使用
このトピックでは、特定の InterSystems IRIS® Data Platform 構成を記したインストール・マニフェストを作成し、これを使用して InterSystems IRIS インスタンスを構成するコードを生成するための %Installer ユーティリティの使用法について説明します。
インストール・マニフェストの概要
%Installer ユーティリティによりインストール・マニフェストを定義します。これは段階的なインストール・プロセスではなく、特定の InterSystems IRIS 構成を記述および構成するものです。これには、通常インストール中 (スーパーサーバ・ポート、オペレーティング・システムなど) に指定した情報を含む変数を使用して、目的の構成を記述した XData ブロックを含むクラスを作成します。また、このクラスにインスタンス構成用のコードを生成するための XData ブロックを使用するメソッドを組み込みます。この付録では、インストール・マニフェストの例を提供します。この例をコピーして貼り付けて、作業を開始することができます。
マニフェストを定義すると、インストール中、またはターミナル・セッションやコードからマニフェストを呼び出すことができます。マニフェストは %SYS ネームスペースで実行する必要があります。
インストール・マニフェストの作成
このセクションでは、インストール・マニフェストの作成に必要な情報を以下の内容に分けて説明します。
マニフェスト・クラス定義
インストール・マニフェストを定義するクラスを作成するには、以下の条件を満たすクラスを作成します (または、以下の "インストール・マニフェストの例" のセクションの空白のテンプレートから開始します)。
-
このクラスには、%occInclude インクルード・ファイルを含める必要があります。
-
このクラスには、インストールの詳細を指定する XData ブロックを含める必要があります。XData ブロックの名前は、後で引数として使用されます。XData ブロックのルート要素は <Manifest> とする必要があります。詳細は、“<Manifest> タグのリスト” を参照してください。
スタジオでは、XData ブロックの名前の後に [XMLNamespace = INSTALLER] を追加すると、XData ブロックの入力に応じてサポートが提供されます。
-
このクラスは、名前で XData ブロックを参照する setup() メソッドを定義する必要があります ("インストール・マニフェストの例" のセクションを参照)。
マニフェストの一般的なオプション
このセクションでは、インストール・マニフェストを使用して実行するいくつかの一般的なタスクについて説明します。以下のオプションについて説明します。
ネームスペースの定義
ネームスペースを定義するには、<Manifest> タグ内に任意の数の <Namespace> タグを追加します。
ネームスペースのデータベースまたはマッピングを定義するには、<Namespace> タグの中に <Configuration> タグを入れます。ネームスペースに含まれるデータベースごとに、<Configuration> タグ内に <Database> タグを追加します。マッピングを定義するには、該当する <Database> タグの下に、<GlobalMapping> タグ、<RoutineMapping> タグ、および <ClassMapping> タグを追加します。</Configuration> タグは、定義されたマッピングを有効化します。
さらに、<Import> タグを使用して、<Namespace> タグ内にグローバル、ルーチン、およびクラスをロードできます。<Invoke> タグでクラス・メソッドを起動してルーチンを実行し、インポートされているグローバルにアクセスすることもできます。
<Var> タグで変数を定義できます。マニフェスト内の変数を参照するには、${var_name} 構文を使用します。詳細は、以下の "<Manifest> タグ内の変数" を参照してください。
ユーザとパスワードの追加
インストールしたインスタンスにユーザ (ロールとパスワードを含む) を追加する方法は複数あります。
-
"<Manifest> タグのリスト" の説明に従って、インストール・マニフェストに <User> タグを含めます。
<User> タグの PasswordVar パラメータはユーザのパスワードを格納した変数を指定します。例えば、PasswordVar="Pwd" を定義すると、変数 Pwd の値がユーザのパスワードに指定されます。この変数にデータを移入する方法は多様ですが、移入方法は担当者次第です。InterSystems IRIS または Web サービスの別のインスタンスに対してメソッドをリモートで呼び出すことも検討できますが、この方法の問題点は、InterSystems IRIS がインストールされているサーバでインターネット・アクセスが必要な場合があることです。インストールしているインスタンスに対して使用するメソッドをインポートするか、ユーザとパスワード (マニフェストに渡すことができます) の入力を求めるインストールにクライアント側フォームを追加する方法も考えられます。
-
インストール完了後に管理ポータルでユーザを編集します ("ユーザ" を参照)。
-
InterSystems IRIS のステージング・インスタンスで Security.UsersOpens in a new tab クラスを使用します (以下を参照)。
-
Security.Users.Export()Opens in a new tab メソッドを使用して、ユーザ情報をエクスポートします。
-
ユーザ情報をインポートするには、(%SYS ネームスペースの) マニフェスト・クラスの先頭で以下を追加します。
<Invoke Class="Security.Users" Method="Import" CheckStatus="true"> <Arg Value="PathToExportedUserInformation"/> </Invoke>
PathToExportedUserInformation は、Security.Users.Export()Opens in a new tab メソッドで指定された出力ファイルの場所です。
-
マニフェスト・ログへの書き込み
次の形式でクラスに <Log> タグを組み込むことで、マニフェスト・ログに追加するメッセージを定義できます。
<Log Level="<level>" Text="<text>"/>
ログのレベルは -1 から 3 までの範囲になる必要があります。-1 は “none” (なし)、3 は “verbose” (詳細) です。setup() メソッドで指定されたログのレベルが <Log> タグの Level プロパティの値以上の場合にメッセージがログに記録されます。テキストは 32,000 文字に制限されます。
setup() メソッドの 2 番目の引数によりレベルを設定します (詳細は、この付録で後述の “マニフェストの使用” を参照)。これはインストールからマニフェストへ渡すことはできないため、次のようにクラスに設定する必要があります。
ClassMethod setup(ByRef pVars, pLogLevel As %Integer = 3,
pInstaller As %Installer.Installer,
pLogger As %Installer.AbstractLogger)
As %Status [ CodeMode = objectgenerator, Internal ]
メッセージの表示位置を setup() メソッドの 4 番目の引数 (%Installer.AbstractLoggerOpens in a new tab) により指定できます。例えば、オペレーティング・システム・ファイルを参照する %Installer.FileLoggerOpens in a new tab オブジェクトをインスタンス化する場合、すべての %Installer およびログ・メッセージはそのファイルに書き込まれます。(この引数がないと、setup() が直接呼び出された場合には、すべてのメッセージがプライマリ・デバイスに書き込まれ、インストーラによって実行された場合には無視されます。)
アップグレード後のタスクの実行
InterSystems IRIS のインスタンスをアップグレードする際、インストール・マニフェストを使用して、コードのリコンパイルなど、必要なアップグレード後のタスクを自動的に実行できます。そのためには、<Invoke> タグを使用して、このドキュメントの “InterSystems IRIS のアップグレード” の章の "ネームスペースのコンパイル方法" のセクションに記載されているクラス・メソッドを呼び出します。
アップグレード時に使用できるマニフェストの例は、この付録の "インストール・マニフェストの例" のセクションを参照してください。
<Manifest> タグ内の変数
一部のタグは、マニフェストが実行されると展開される式 (文字列) を含めることができます。展開できる式には 3 種類あります (下記参照)。
変数の値に展開されます。このセクションで説明する事前定義変数のほかに、<Var> タグで追加の変数を指定できます。
マニフェスト・クラスの指定されたパラメータの値に展開します。
指定された InterSystems IRIS Object Script 式に展開します (正しく引用符を付ける必要があります)。
パラメータの式はコンパイル時に展開されます。つまり、変数および ObjectScript 式の内側で入れ子にできます。また、変数の式は ObjectScript 式の前に展開されるため、後者の内側で入れ子にできます。
以下のテーブルに、マニフェストで使用できる事前定義変数を示します。
変数名 | 説明 |
---|---|
SourceDir | (インストーラ実行中にのみ使用可能) インストール (setup_irisdb.exe または irisinstall) の実行元となるディレクトリ。 |
ISCUpgrade | (インストーラ実行中にのみ使用可能) 新規インストールまたはアップグレードであるかを示します。この変数は 0 (新規インストール) または 1 (アップグレード) のいずれかになります。 |
CFGDIR | "INSTALLDIR" を参照してください。 |
CFGNAME | インスタンス名。 |
CPUCOUNT | オペレーティング・システムの CPU の数。 |
CSPDIR | CSP ディレクトリ。 |
HOSTNAME | ホスト・サーバの名前。 |
INSTALLDIR | InterSystems IRIS がインストールされるディレクトリ。 |
MGRDIR | 管理者用 (mgr) ディレクトリ。 |
PLATFORM | オペレーティング・システム。 |
PORT | InterSystems IRIS スーパーサーバ・ポート。 |
PROCESSOR | プロセッサ・チップ。 |
VERSION | InterSystems IRIS のバージョン番号。 |
マニフェストの使用
マニフェストは、手動で実行することも、インストールの一部として実行することもできます。
手動で実行する場合
%SYS ネームスペースで、ターミナルに以下のコマンドを入力します。
%SYS>do ##class(MyPackage.MyInstaller).setup()
変数の配列を参照として setup() メソッドに渡すことができます。各添え字は変数名として使用され、ノードは値として使用されます。以下に例を示します。
%SYS>set vars("SourceDir")="c:\myinstaller"
%SYS>set vars("Updated")="Yes"
%SYS>do ##class(MyPackage.MyInstaller).setup(.vars,3)
この例の 2 番目の引数 (3) は、ログ・レベルです。
インストール時に実行する場合
マニフェスト・クラスを DefaultInstallerClass.xml として InterSystems IRIS インストール (.msi、setup_irisdb.exe、または irisinstall) が実行されている場所と同じディレクトリにエクスポートします。これは %SYS にインポートされてコンパイルされ、setup() メソッドが実行されます。
インストールを実行するユーザが、マニフェスト・ログ・ファイル・ディレクトリへの書き込み許可を持っていることを確認します。ログ・ファイルに書き込めない場合、インストールは続行されません。
また、単一ファイル・キットを使用してインストールしている場合、想定どおりに動作するようにするには、ファイルを .exe ファイルからインストール・ディレクトリに抽出する必要があります。
エクスポートする方法では、引数を setup() メソッドに直接渡せないことに注意してください。以下のセクションでは、Windows で、または UNIX®、Linux、および macOS で引数を渡す方法について説明します。
Windows
.msi インストール・パッケージを変更して、変数の名前と値のペアを setup() メソッドに渡すことができます。
また、以下の例に示すようにインストーラでコマンド行引数を使用して、エクスポートされるマニフェスト・クラスの場所、変数、ログ・ファイル名、およびログのレベルを渡すこともできます。
setup.exe INSTALLERMANIFEST="c:\MyStuff\MyInstaller.xml"
INSTALLERMANIFESTPARAMS="SourceDir=c:\mysourcedir,Updated=Yes"
INSTALLERMANIFESTLOGFILE="installer_log" INSTALLERMANIFESTLOGLEVEL="2"
INSTALLERMANIFESTPARAMS 引数を使用して渡される変数名には、アルファベット文字と数字 (A-Za-z0-9)、およびアンダースコア (_) のみを含めることができますが、先頭をアンダースコアにすることはできません。
詳細は、"コマンド行のリファレンス" を参照してください。
UNIX®、Linux、および macOS
UNIX®、Linux、および macOS システムでは、以下の例に示すように、irisinstall または irisinstall_silent のいずれかを実行する前に環境変数を設定して、エクスポートされるマニフェスト・クラスの場所、変数、ログ・ファイル名、およびログのレベルを定義できます。
ISC_INSTALLER_MANIFEST="/MyStuff/MyInstaller.xml"
ISC_INSTALLER_PARAMETERS="SourceDir=/mysourcedir,Updated=Yes"
ISC_INSTALLER_LOGFILE="installer_log"
ISC_INSTALLER_LOGLEVEL="2"
./irisinstall
詳細は、"自動インストール・パラメータ" を参照してください。
インストール・マニフェストの例
このセクションでは、以下を行うインストール・マニフェストの例を示します。
空のテンプレート
以下に、基本的なマニフェスト・テンプレートを示します。
Include %occInclude
/// Simple example of installation instructions (Manifest)
Class MyInstallerPackage.SimpleManifest
{
XData SimpleManifest [ XMLNamespace = INSTALLER ]
{
<Manifest>
<Log Level="3" Text="Start manifest" />
<Namespace Name="">
<Import File="" />
<Invoke Class="" Method="" CheckStatus="" Return="">
<Arg Value=""/>
</Invoke>
</Namespace>
<CopyFile Src="" Target="" IgnoreErrors=""/>
<CopyDir Src="" Target="" IgnoreErrors=""/>
<Log Level="3" Text="End manifest" />
</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")
}
}
ネームスペースの作成
この例のマニフェストでは、ネームスペース (MyNamespace) と 3 つのデータベースを作成します。MyDataDB データベースと MyRoutinesDB データベースはそれぞれグローバルとルーチンの既定のデータベースで、MyMappingDB データベースは別のグローバル・データベースです。<GlobalMapping> タグは、MyNamespace ネームスペースにある t* グローバルに対して MyMappingDB へのマッピングを作成します。これは、既定のマッピングをオーバーライドします。
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")
}
}
アップグレード後のコンパイル
この例のマニフェストでは APPTEST という名前のネームスペース内のコードをリコンパイルし、アップグレード後に実行します。以下のタスクを実行します。
-
マニフェスト・インストール・プロセスの開始を示すメッセージをマニフェスト・ログに書き込みます。
-
現在のネームスペースを APPTEST に設定します。これには、アップグレード後にリコンパイルする必要のあるコードが含まれます。
-
メソッド %SYSTEM.OBJ.CompileAll() を呼び出して、ネームスペース内のクラスをコンパイルします。
-
メソッド %Routine.CompileAll() を呼び出して、ネームスペース内のカスタム・ルーチンをコンパイルします。
-
マニフェスト・インストール・プロセスの終了を示すメッセージをマニフェスト・ログに書き込みます。
Include %occInclude
/// Simple example of installation instructions (Manifest)
Class MyInstallerPackage.SimpleManifest
{
XData SimpleManifest [ XMLNamespace = INSTALLER ]
{
<Manifest>
<Log Level="3" Text="The Installer Manifest is running."/>
<Namespace Name="APPTEST">
<Invoke Class="%SYSTEM.OBJ" Method="CompileAll" CheckStatus="1">
<Arg Value="u"/>
</Invoke>
<Invoke Class="%Routine" Method="CompileAll" CheckStatus="1"/>
</Namespace>
<Log Level="3" Text="The Installer Manifest has completed."/>
</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")
}
}