SAP BusinessObjects Web Intelligence 拡張ポイント：カスタム関数の構築

Transcription

1 SAP BusinessObjects Web Intelligence 拡張ポイント : カスタム関数の構築 SAP BusinessObjects XI 3.1 Service Pack 3 windows and linux

2 著作権 2010 SAP AG. All rights reserved.sap R/3 SAP NetWeaver Duet PartnerEdge ByDesign SAP Business ByDesign および本書に記載されたその他のSAP 製品 サービス ならびにそれぞれのロゴは ドイツおよびその他の国々におけるSAP AGの商標または登録商標です Business ObjectsおよびBusiness Objects ロゴ BusinessObjects Crystal Reports Crystal Decisions Web Intelligence Xcelsius および本書で引用されているその他のBusiness Objects 製品 サービス ならびにそれぞれのロゴは 米国およびその他の国々におけるBusiness Objects S.A. の商標または登録商標です Business ObjectsはSAPのグループ企業です 本書に記載されたその他すべての製品およびサービス名は それぞれの企業の商標です 本書に記載されたデータは情報提供のみを目的として提供されています 製品仕様は 国ごとに変わる場合があります これらの文書の内容は 予告なしに変更されることがあります また これらの文書はSAP AGおよびその関連会社 ( SAP グループ ) が情報提供のためにのみ提供するもので いかなる種類の表明および保証を伴うものではなく SAPグループは文書に関する誤記 脱落等の過失に対する責任を負うものではありません SAPグループの製品およびサービスに対する唯一の保証は 当該製品およびサービスに伴う明示的保証がある場合に これに規定されたものに限られます 本書のいかなる記述も 追加の保証となるものではありません

3 目次 第 1 章 計算拡張の概要 5 外部関数...6 カスタム関数のデプロイメント...7 ライブラリ宣言...7 Web Intelligence サンプルファイルの使用...8 第 2 章 カスタム計算の定義 9 XML 関数オブジェクト...10 XML 関数宣言の定義...13 XML カタログ宣言の定義...14 C++ ファイルの実装...15 Microsoft Visual Studio 2005 のソースファイルのコンパイル...16 WebiCalcPlugin へのファイルのコピー...17 第 3 章 例 19 第 4 章 エラーメッセージ 23 #EXTERNAL エラーメッセージ...24 トレースログメッセージエラー...24 付録 A より詳しい情報 27 索引 31 SAP BusinessObjects Web Intelligence 拡張ポイント : カスタム関数の構築 3

4

5 計算拡張の概要 1

6 計算拡張の概要 1 外部関数 計算拡張はカスタム Web Intelligence レポート計算で 既存の Web Intelligence 関数リストを拡張するものです 計算拡張ライブラリを使用するには 特定の API が後に続く C++ 外部ライブラリを作成します Web Intelligence の高度な計算機能や Web Intelligence 関数や演算子への構文参照については SAP ヘルプポータルからダウンロードできる Web Intelligence における関数 式 計算の使い方 を参照してください 外部関数 外部関数は 他の Web Intelligence 標準関数のように表示され 使用することができます 独自の論理を実装する関数を使用してフォーミュラを構築することができます 注関数は好きなだけ定義できます 単一値パラメータを使用している関数のみがサポートされます 最大で 5 つの単一値パラメータを持つことができます 関数を定義する 1 指定の XML 構造を使用して外部関数の説明を XML ファイルに宣言します 2 指定の API を使用して C++ ライブラリの関数を実装します 3 XML ファイルおよびライブラリを サーバーおよびデスクトップクライアントの Business Objects Enterprise インストールディレクトリフォルダにある該当フォルダにコピーします 4 システムを再起動して フォーミュラの作成に使用できる関数一覧に自動的に外部関数を追加します 外部関数は レポートで使用される際に 異なる外部ライブラリを使用する場合に誤解釈できないように 一意の識別子に基づいています システムでライブラリをロードできない 外部関数の情報が存在しない 整合性のない XML 宣言 ライブラリが存在しない または関数が重複している場合 エラーメッセージが表示されます またトレースログにエラーが書き込まれます 関連項目 24 ページの #EXTERNAL エラーメッセージ 6 SAP BusinessObjects Web Intelligence 拡張ポイント : カスタム関数の構築

7 計算拡張の概要カスタム関数のデプロイメント 1 カスタム関数のデプロイメント カスタム関数のデプロイメントには いくつかの手動の手順が必要です BusinessObjects 管理者は XML ファイルおよび関連ライブラリ DLL ファイルをサーバーのライブラリフォルダと デスクトップリッチクライアント上に配置する必要があります 警告 カスタムライブラリフォルダでライブラリの置換や追加を行うと システムに悪影響を与える可能性があります ライブラリは自動的にロードされるため 外部ライブラリが内部の重要なデータやプロセスにアクセスできるようになり システムを危険にさらす可能性があります サイト管理者は関連フォルダに対して適切なセキュリティアクセスを実装して 許可された人のみがカスタムライブラリフォルダにアクセスするようにします ライブラリ宣言 ライブラリファイルの拡張子はオペレーティングシステムによって異なります Windows の場合は DLL Linux または UNIX の場合は SO ファイルの種類は次のとおりです 種類 説明 XML カタログ宣言 この種類のファイルは 1 つのみで externalcatalogs.xml という名前になります このファイルには すべての XML 関数定義ファイルの一覧が含まれています XML 関数宣言 このファイルは 関数およびその関連ライブラリの一覧を定義したもので XML カタログ宣言ファイルに表示されています 注カタログファイルは 関数宣言ライブラリを含めるか参照することができます SAP BusinessObjects Web Intelligence 拡張ポイント : カスタム関数の構築 7

8 計算拡張の概要 1 Web Intelligence サンプルファイルの使用 種類 説明 ライブラリファイル このファイルには C++ で記述されたユーザー関数のコードが含まれています ライブラリファイルには XML 関数宣言で定義されているユーザー関数実装が含まれています Web Intelligence サンプルファイルの使用 以下のアプリケーションをインストールしておく必要があります Visual Studio C++ Web Intelligence XI 3.1 SP2 この例では VS2005_Samples.zip ファイルにあるサンプルファイルを使用しています これは [Install directory]\userlibs\webi\samples\ にあります 注このサンプルは VS2008 でも動作しますが VS2008 を開く際に VS2008 によってサンプルが移行されます 1 VS2005_Samples.zip を解凍します 2 サンプルを開くには OpenSolution.bat を起動します OpenSolution.bat により ソリューションで使用される一時 WEBICALCPLUGINAPI 変数環境が設定され Web Intelligence 固有のヘッダーファイルが検索されます 警告 Web Intelligence の必須バージョンがインストールされていない場合 OpenSo lution.bat を使用できません Web Intelligence ヘッダーファイルを含むフォルダのパスを使用して WEBICALCPLUGINAPI 変数環境を手動で設定します VS2005_Samples\WebICalcPlugIn を開きます 関連項目 19 ページの 例 8 SAP BusinessObjects Web Intelligence 拡張ポイント : カスタム関数の構築

9 カスタム計算の定義 2

10 カスタム計算の定義 2 XML 関数オブジェクト Web Intelligence 内の関数をカスタマイズするには 次のように行います 1 XML 関数宣言を定義します 2 XML カタログ宣言を定義します 3 外部関数の特定 API を使用して C++ 内にライブラリを実装します 4 ソースファイルをコンパイルします 5 XML 定義およびライブラリを専用 WebiCalcPlugin フォルダにコピーします ( サーバー側と任意のリッチクライアント ) 6 Web Intelligence サーバーを再起動します 注この章の例では Web Intelligence に添付のサンプルファイルを使用しています 式エディタと数式バーのホップヒントの関数一覧に関数が自動的に追加されます フォーミュラが外部ライブラリの使用できない関数を使用している場合 #EXTERNAL エラーメッセージが表示されます 注単一値パラメータを使用している関数のみがサポートされます XML 関数オブジェクト XML 定義には カスタム関数を定義するオブジェクトが含まれています XML カスタム関数は フォーミュラ言語の関数の一覧を拡張して この関数を使用するフォーミュラが XML 署名に従って解析され トークン化された形に変換されるようになります 外部関数にグローバル一意識別子 (GUID) を割り当てて 再利用できないようにしたり 他のカスタムライブラリと取り違えないようにすることができます XML 定義には次のオブジェクトが含まれています タグ XML 属性 XML 定義オブジェクト CATALOG XML ルート LIBRARY ファイル C++ 実装コードを含むライブラリファイル名 ライブラリファイルに複数の関数を含めることができます ライブラリ拡張子は指定されません 10 SAP BusinessObjects Web Intelligence 拡張ポイント : カスタム関数の構築

11 カスタム計算の定義 XML 関数オブジェクト 2 タグ XML 属性 XML 定義オブジェクト FUNCTION guid 名前 一意関数 GUID ヒントあらかじめすべての GUID を定義して すべての GUID が全体的な視点から一意であることを確認します Windows の場合 Visual Studio に付属している GUID ツールを使用することができます これは Microsoft の Web サイトからダウンロードすることも可能です Linux の場合 ツール usr/bin/uuidgen が libuuid1(debian) パッケージにあります 式エディタ内に表示される関数名 関数名は以下の条件を満たす必要があります 関数を表す簡単な一意の名前である 文字で始まる 大文字 小文字 数字 または _ 文字を使用する Web Intelligence ライブラリにまだ存在していない 注名前は変換されません ARGLIST パラメータの一覧 数は 5 つ未満です SAP BusinessObjects Web Intelligence 拡張ポイント : カスタム関数の構築 11

12 カスタム計算の定義 2 XML 関数オブジェクト タグ XML 属性 XML 定義オブジェクト ARG 型 パラメータの型 使用可能なパラメータの型は以下のとおりです 数値 論理式 日付 文字列 名前 式エディタ内に表示される各パラメータ名 名前は ユーザーにメソッドのプロトタイプを示します 英数字のみを使用します RETURN 型 戻り値の型 戻り値は次のとおりです 数値 論理式 日付 文字列 CATEGORY 型 式エディタ内で関数が表示されるカテゴリ 一貫性のあるものにします 文字カテゴリに文字列を配置し 数値カテゴリに数字を配置します 使用可能なカテゴリは 次のとおりです Character Date Document DP Misc Logical Num 12 SAP BusinessObjects Web Intelligence 拡張ポイント : カスタム関数の構築

13 カスタム計算の定義 XML 関数宣言の定義 2 タグ XML 属性 XML 定義オブジェクト HINT 値 式エディタ内に表示されるヒント ヒントは 関数の使用法を説明したものです XML 関数宣言の定義 署名用の XML は以下の構造を使用します Function_list 署名用の XML は以下の構造を使用します Function_list := [Function*] Function := [name, GUID, data_type = Numeric Boolean Date String, category = character Date Document DP Misc Logical Num, parameter_list, (online_help_signature?), (online_help_description?),library_name)] parameter_list := [parameter*] parameter := [name, data_type =Numeric Boolean Date String] 1 XML ルートタグを CATALOG に設定します 2 CATALOG に LIBRARY タグを追加します 3 LIBRARY に DLL または SO ファイル拡張子を除いたライブラリファイル名を追加します これがファイル属性です 4 LIBRARY に FUNCTION タグを追加します FUNCTION タグには一意の GUID と 追加で関数名を定義する一意の属性名があります FUNCTION タグには次のものが含まれます ARG タグのある ARGLIST タグ ARG タグには このパラメータの種類を定義する 1 番目の属性と このパラメータの名前を定義する 2 番目の属性があります ARG の型は 論理型 数値 日付 文字列のいずれかです ARG 名には英数字のみを使用できます 注パラメータは 5 つまでに制限されています SAP BusinessObjects Web Intelligence 拡張ポイント : カスタム関数の構築 13

14 カスタム計算の定義 2 XML カタログ宣言の定義 型属性を定義する RETURN タグ RETURN の型は 論理型 数値 日付 文字列のいずれかです 型属性を定義する CATEGORY タグ CATEGORY の型は 文字 日付 ドキュメント DP その他 論理型 または数値のいずれかです 値属性を定義する HINT タグ 5 XML 定義を専用フォルダ ( サーバー側および任意のリッチクライアント ) に配置します 例 SampleMath.xml <CATALOG> <LIBRARY file="samplemath"> <FUNCTION guid="cc3e a dbf-2ccd4f6ecabe" name="mysquarefct"> <ARGLIST> <ARG type="numeric" name="input_number"/> </ARGLIST> <RETURN type="numeric"/> <CATEGORY type="num"/> <HINT value="my square function."/> </FUNCTION> </LIBRARY> </CATALOG> 関連項目 8 ページの Web Intelligence サンプルファイルの使用 XML カタログ宣言の定義 XML カタログ宣言を作成したり 既存のカタログ宣言に XML カタログ宣言を追加することができます <CATALOG> は XML 関数宣言を参照します 参照しない場合は XML 関数宣言形式を定義するセクションで示されているとおりに直接 <CATALOG> を定義します カタログ宣言を作成するには 次のように行います 1 宣言 externalcatalogs.xml を命名します 14 SAP BusinessObjects Web Intelligence 拡張ポイント : カスタム関数の構築

15 カスタム計算の定義 C++ ファイルの実装 2 2 XML ルートタグを CATALOGS に設定します 3 CATALOGS に CATALOG タグを追加します このアクションは XML 関数宣言のファイル名値を定義するものです 4 XML ライブラリを専用フォルダ ( サーバー側および任意のリッチクライアント ) に配置します 例 externalcatalogs.xml <CATALOGS> <CATALOG file="samplemath.xml"/> </CATALOGS> 関連項目 8 ページの Web Intelligence サンプルファイルの使用 C++ ファイルの実装 1 ファイルに ibovariant.h ヘッダーを追加します 2 各メソッドに対して BO_DECLARE_USER_FCT マクロで宣言を開始します マクロには次のものが含まれます XML 関数宣言ファイルに表示される関数名 戻り値オブジェクト名 パラメータオブジェクト名 注何も問題がない場合 関数は BONOERROR を返します 問題がある場合は #EXTERNAL エラーメッセージがレポートに表示されます 例 Square.cpp // Headers file include of the WebI hearders #include <ibovariant.h> // To not repeat BOExtFunct:: using namespace BOExtFunct; BO_DECLARE_USER_FCT (// Name of function as it was defined in the XML. MySquareFct, // Name of the return value object. SAP BusinessObjects Web Intelligence 拡張ポイント : カスタム関数の構築 15

16 カスタム計算の定義 2 Microsoft Visual Studio 2005 のソースファイルのコンパイル { } retval, // Name of the parameters object. parameters ) try // Always used a try{}catch( ) to be sure no // exception was thrown outside this Web // Intelligence user function. { // Get the first parameter. const ibovalue&param0 = parameters[0]; // Transform the parameter to the correct type. double valpar0(param0); // Assign value to the return value. retval = valpar0 * valpar0; } catch(...) { return BOERROR; // Unkonwn exception so notify WebI } return BONOERROR; // It's OK 関連項目 8 ページの Web Intelligence サンプルファイルの使用 Microsoft Visual Studio 2005 のソースファイルのコンパイル 1 プロジェクトを作成するには [ ファイル ] > [ 新規作成 ] > [ プロジェクト ] に移動します 2 [ プロジェクトの種類 ] で [Visual C++] > [ 全般 ] を選択します 3 [ テンプレート ] で [ 空のプロジェクト ] を選択します 4 プロジェクト名を指定します 5 プロジェクトの出力先フォルダを指定します 6 [OK] をクリックします 7 プロジェクトを右クリックして [ プロパティ ] を選択します 8 [ 構成 ] で [ すべての構成 ] を選択します 9 [ 構成プロパティ ] > [ 全般 ] で [ 構成の種類 ] を [ ダイナミックライブラリ (.dll)] に設定します 16 SAP BusinessObjects Web Intelligence 拡張ポイント : カスタム関数の構築

17 カスタム計算の定義 WebiCalcPlugin へのファイルのコピー 2 10 [OK] をクリックします 11 プロジェクトを右クリックして [ 追加 ] > [ 新規項目 ] を選択します 12 [ カテゴリ ] で [ コード ] を選択します 13 [ テンプレート ] で [C++ ファイル (.CPP)] を選択します 14 CPP ファイル名を指定します 15 [ 追加 ] をクリックします 16 プロジェクトを右クリックして [ プロパティ ] を選択します 17 [ 構成 ] で [ すべての構成 ] を選択します 18 [ 構成プロパティ ] > [C/C++] で Business Objects ファイルヘッダーを含むフォルダを追加します 19 [ 適用 ] をクリックします 20 [ 構成 ] で [ デバッグ ] を選択します 21 [ 構成プロパティ ] > [C/C++] > [ コード生成 ] で [ マルチスレッドデバッグ (/MTd)] に設定します 22 [ 適用 ] をクリックします 23 [ 構成 ] で [ 解放 ] を選択します 24 [ 構成プロパティ ] > [C/C++] > [ コード生成 ] で [ マルチスレッド (/MT)] に設定します 25 [OK] をクリックします 26 コードを CPP ファイルに追加します 27 コンパイルを行います WebiCalcPlugin へのファイルのコピー XML 関数宣言 XML カタログ宣言 および DLL/SO ファイルを bin フォルダの WebiCalcPlugIn セクションにコピーします ファイルは Windows デプロイメントの次のパスにあります [installation directory]\[businessobjects Version]\[OS]_[PLATEFORM]\WebiCalcPlugIn ここで [BusinessObjects Version] は BusinessObjects Enterprise 12.0 など製品のバージョンにあたります また [OS] はオペレーティングシステムであり オペレーティングシステムが Windows の場合は win32 Linux の場合は linux などとなります [PLATEFORM] はプラットフォームで たとえば Intel 32 ビット中央処理装置の場合は x86 となります SAP BusinessObjects Web Intelligence 拡張ポイント : カスタム関数の構築 17

18

19 例 3

20 3 例 この例では VS2005_Samples.zip ファイルにあるサンプルファイルを使用しています これは [Install directory]\userlibs\webi\samples\ にあります 例 externalcatalogs.xml の XML カタログ宣言 <CATALOGS> <CATALOG file="samplestring.xml"/> </CATALOGS> 例 SampleString.xml の XML 関数宣言 <CATALOG> <LIBRARY file="samplestring"> <FUNCTION guid="a91bd526-b8eb-4b09-90f2-ffcd350776a8" name="myhelloworld"> <RETURN type="string"/> <CATEGORY type="num"/> <HINT value="my simple hello world function."/> </FUNCTION> </LIBRARY> </CATALOG> 例 HelloWorld.cpp の C++ ファイル宣言 // Headers file include of the Web Intelligence hearders #include <ibovariant.h> // To not repeat BOExtFunct:: using namespace BOExtFunct; BO_DECLARE_USER_FCT( // Name of function as it was defined in the XML. MyHelloWorld, // Name of the return value object. retval // Don't use parameter. /*parameters*/ ) { try // Always used a try{}catch( ) to be sure no // exception was thrown outside this // Web Intelligence user function. { 20 SAP BusinessObjects Web Intelligence 拡張ポイント : カスタム関数の構築

21 例 3 } // Create an std::wstring with wide char Hello world. std::wstring helloworldstr = L"Hello world!!!"; // Initialyse the return value. retval = helloworldstr; } catch(...) { // Unkonwn exception so notify Web Intelligence return BOERROR; } return BONOERROR; // It s OK 関連項目 8 ページの Web Intelligence サンプルファイルの使用 SAP BusinessObjects Web Intelligence 拡張ポイント : カスタム関数の構築 21

22

23 エラーメッセージ 4

24 エラーメッセージ 4 #EXTERNAL エラーメッセージ #EXTERNAL エラーメッセージ 次のような問題により #EXTERNAL エラーメッセージが生成されます フォーミュラが外部ライブラリフォルダにはない外部関数を参照している ドキュメントに外部メソッドが含まれていて システムがこれをロードできない ライブラリファイルが見つからないか 不整合な宣言が含まれている 外部メソッドが戻り値を初期化しない 外部メソッドが戻り値を不正な型に初期化した たとえば 浮動小数点型が文字列型に設定されている場合などがあります 外部メソッドがエラーコードを返した BusinessObjects 管理者にこの関数を実装する正しいライブラリをデプロイするように依頼してください トレースログメッセージエラー XML 解析 / 検証中にエラーが発生した場合 ユーザーに対してメッセージが提示され エラーがトレースログに入力されます ログの種類 エラーメッセージ File cannot be read or is missing. XML ログ Bad XML structure due to: Parent/Children relation invalid. Missing field (ID function, name function). Invalid field value. File is missing. DLL ログ DLL cannot be loaded. Function is not found in the DLL. 24 SAP BusinessObjects Web Intelligence 拡張ポイント : カスタム関数の構築

25 エラーメッセージトレースログメッセージエラー 4 ログの種類 エラーメッセージ Function name is already in use. Function ID is already used. 関数ログ Function name is missing. Return type is invalid. ID is invalid. Number of parameters is invalid. パラメータログ Parameter name is missing. Parameter type is invalid. The user function does not initialize the return value. ランタイムログ The user function initializes the return value with a bad type. The user function returns the BOERROR error code. SAP BusinessObjects Web Intelligence 拡張ポイント : カスタム関数の構築 25

26

27 より詳しい情報 A

28 A より詳しい情報 情報リソース SAP BusinessObjects 製品情報 場所 から SAP BusinessObjects を選択します SAP ヘルプポータル SAP ヘルプポータルでは すべての SAP BusinessObjects 製品とそのデプロイメントについて扱った最新のドキュメンテーションにアクセスできます PDF 版またはインストール可能な HTML ライブラリのダウンロードが可能です 一部のガイドは SAP サービスマーケットプレイスに格納されており SAP ヘルプポータルからは入手できません ヘルプポータルのガイド一覧で そのようなガイドには SAP サービスマーケットプレイスへのリンクが付いています メンテナンス契約を締結されたお客様には このサイトにアクセスするための正規ユーザー ID が付与されます ID の入手方法については お客様担当のカスタマーサポート担当者までお問い合わせください SAP サービスマーケットプレイス > ドキュメンテーション インストールガイド : guides リリースノート : SAP サービスマーケットプレイスには 一部のインストールガイド アップグレードおよび移行ガイド デプロイメントガイド リリースノート サポート対象プラットフォームに関するドキュメントが格納されています メンテナンス契約を締結されたお客様には このサイトにアクセスするための正規ユーザー ID が付与されます ID の入手方法については お客様担当のカスタマーサポート担当者までお問い合わせください SAP ヘルプポータルから SAP サービスマーケットプレイスにリダイレクトされた場合は 左側のナビゲーションペインのメニューを使用して アクセスするドキュメンテーションが含まれているカテゴリを探します 28 SAP BusinessObjects Web Intelligence 拡張ポイント : カスタム関数の構築

29 より詳しい情報 A 情報リソース 場所 開発者向けリソース SAP Community Network 上の SAP BusinessObjects に関する記事 これらの記事は 以前はテクニカルペーパーという名称でした ノート これらのノートは 以前はナレッジベース記事という名称でした SAP Community Network 上のフォーラム トレーニング 伝統的な教室での学習から的を絞った e ラーニングセミナーまで それぞれのニーズと希望する学習スタイルに応じた幅広いトレーニングパッケージを提供しております オンラインカスタマーサポート SAP サポートポータルには カスタマーサポートプログラムとサービスに関する情報が含まれています また さまざまなテクニカル情報およびダウンロードへのリンクも用意されています メンテナンス契約を締結されたお客様には このサイトにアクセスするための正規ユーザー ID が付与されます ID の入手方法については お客様担当のカスタマーサポート担当者までお問い合わせください SAP BusinessObjects Web Intelligence 拡張ポイント : カスタム関数の構築 29

30 A より詳しい情報 情報リソース 場所 sulting コンサルティング コンサルタントは 初期の分析段階からデプロイメントプロジェクトの実現まで一貫したサポートを提供します リレーショナルデータベースと多次元データベース 接続 データベース設計ツール カスタマイズされた埋め込みテクノロジなどのトピックに関する専門的なサポートを行います 30 SAP BusinessObjects Web Intelligence 拡張ポイント : カスタム関数の構築

31 索引 記号 #EXTERNAL 10, 24 B BO_DECLARE_USER_FCT 15 C C++ ファイル実装 15 E ExternalFunc.xml 6 G GUID 6, 10 W WebiCalcPlugIn 7, 17 え エラー関数内 24 エラー ( 続き ) トレースログ 24 か 関数 XML カタログ宣言 14 XML 宣言 13 エラー 24 構造 10 し 式エディタ 10 そ ソースファイルコンパイル 16 と トレースログエラーメッセージ 24 ら ライブラリファイル構造 7 SAP BusinessObjects Web Intelligence 拡張ポイント : カスタム関数の構築 31

32