<assign>
構文
<assign property="propertyname" value="expression" />
詳細
属性または要素 | 説明 | 値 |
---|---|---|
property 属性 | 必須項目。この割り当てのターゲット。実行コンテキスト・オブジェクトのプロパティを指定する必要があります (通常は、context、request、response、callrequest、または callresponse)。 詳細は、以下の "説明" トピックの表を参照してください。 | 1 文字以上の文字列。 |
value 属性 | 必須項目。プロパティの値。 | プロパティに有効な値を返すリテラル値または式。式の場合は、この属性が含まれる <process> 要素で指定されているスクリプト言語を使用する必要があります。 |
action 属性 | オプション。property がコレクション (リストまたは配列) の場合は、action を使用して、そのコレクションに対して行う割り当てのタイプを指定します。指定しない場合、set が実行されます。 | リテラル文字列 append、set、clear、insert、または remove (この後の説明を参照)。 |
key 属性 | property がコレクション (リストまたは配列) である一部の場合を除き、オプション。コレクションの場合は、このキーを使用して、この割り当てのターゲットであるコレクションのメンバを指定します。 | キーを求める式。 |
name、disabled、xpos、ypos、xend、yend 属性 | "一般的な属性と要素" を参照してください。 | |
<annotation> 要素 |
説明
ここでは、BPL ビジネス・プロセスにおける実行コンテキストの重要性、および <assign> 要素を使用して、ビジネス・プロセスの実行コンテキストの値を設定する方法を説明します。
ビジネス・プロセスでは、実行を中断するたびに状態情報をディスクに保存し、再開するときは、その状態情報をディスクからリストアする必要があります。この機能は、完了までに数日または数週間かかる可能性のある長期実行のビジネス・プロセスにおいては特に重要です。この要件に対応するため、InterSystems IRIS のすべての BPL ビジネス・プロセスには、実行コンテキストと呼ばれる一連のオブジェクトと変数があります。実行コンテキストの変数は、BPL ビジネス・プロセスが実行を中断および再開するたびに自動的に保存、リストアされます。BPL ビジネス・プロセスを適切に実行するには、これらの変数を正しく使用する必要があります。
実行コンテキストの変数には、それぞれ特定の名前と目的が与えられています。これらの変数には、<assign> 要素を使用して値を設定できます。以下は、実行コンテキストの変数一覧です。
変数 | 目的 |
---|---|
callrequest | callrequest オブジェクトには、<call> が送信する要求メッセージ・オブジェクトの構築に必要となるすべてのプロパティが含まれます。対応する <request> アクティビティ内で一連の <assign> 要素を使用して、callrequest にプロパティ値を設定します。 |
callresponse | <call> アクティビティが完了すると、callresponse オブジェクトには、<call> に返される応答メッセージ・オブジェクトのプロパティが追加されます。対応する <response> アクティビティ内で一連の <assign> 要素を使用して、callresponse のプロパティから context または response のプロパティに戻り値をコピーします。 |
context | context オブジェクトは、ビジネス・プロセスの汎用データ・コンテナです。context は自動的には定義されません。このオブジェクトのプロパティを定義するには、<context> 要素を使用します。その場合、<process> 要素内でこれらのプロパティを参照するには、context.Balance のようにドット構文を使用します。 |
request | request オブジェクトには、このビジネス・プロセスをインスタンス化させた元の要求メッセージ・オブジェクトのプロパティが含まれます。<process> 要素内で request のプロパティを参照するには、request.UserID のようにドット構文を使用します。 |
response | response オブジェクトには、ビジネス・オブジェクトが返す最終的な応答メッセージ・オブジェクトの構築に必要となるすべてのプロパティが含まれます。<process> 要素内で response のプロパティを参照するには、response.IsApproved のようにドット構文を使用します。これらのプロパティに値を割り当てるには <assign> 要素を使用します。 |
status | status は、成功または失敗を示す %StatusOpens in a new tab 型の値です。BPL ビジネス・プロセスの実行中に status が失敗値を受け取ると、そのビジネス・プロセスは即座に終了し、失敗の理由を示すテキスト・メッセージがイベント・ログに書き込まれます。通常、<call> アクティビティから不成功値が返された時点で、この処理が自動的に行われます。ただし、<assign> または <code> を使用して status 値を設定すれば、BPL ビジネス・プロセス・コードをいつでも正常に終了できます。このトピックの最後の説明を参照してください。 |
syncresponses | syncresponses は応答オブジェクトのコレクションであり、同期している <call> アクティビティの名前がキーとなります。完了した呼び出しのみが示されます。syncresponses から応答を取得できるのは、<sync> を実行してから、現在の <sequence> の終了までの間に限られます。該当する呼び出しが <call name="MyName"> として定義されている syncresponses.GetAt("MyName") 構文を使用して応答を取得します。 |
synctimedout |
synctimedout 値は整数です。synctimedout は、いくつかの呼び出し後の <sync> アクティビティの結果を示します。synctimedout の値をテストできるのは、<sync> を実行してから、該当する呼び出しと <sync> を含む <sequence> の終了までです。synctimedout の値は、以下の 3 つのいずれかになります。
通常、synctimedout を取得してステータスを確認し、その後、syncresponses コレクションの完了した呼び出しから応答を取得します。 |
その他すべての実行コンテキスト変数名と同様、status は BPL の予約語です。上記の場合を除き、<assign> でこの予約語を使用しないでください。
BPL の <assign> 要素は、ターゲットと、そのターゲットに割り当てられる式を指定します。ターゲットとしては、ビジネス・プロセスの実行コンテキストのいずれかのオブジェクトのプロパティ、またはいずれかの単値変数 (status など) を使用できます。<assign> 要素に含まれるプロパティは、データ型、オブジェクト、またはこれらいずれかのコレクションです。コレクション・プロパティを宣言するには、対応する <property> 要素で、collection 属性を “array” または “list” に設定します。
上の表で説明したように、context と呼ばれるオブジェクトは、ビジネス・プロセスの汎用コンテキスト・オブジェクトとして機能します。context オブジェクトのプロパティを定義するには、<process> 環境の先頭に <context> 要素と <property> 要素を配置します。以下に例を示します。
<process request="Demo.Loan.Msg.Application" response="Demo.Loan.Msg.Approval">
<context>
<property name="CreditRating" type="%Integer"/>
<property name="PrimeRate" type="%Numeric"/>
</context>
...
</process>
上記の BPL では、このビジネス・プロセスの 2 つの context プロパティ (context.CreditRating と context.PrimeRate) を定義しています。ただし、値は割り当てていません。<process> 環境内で、この <context> 要素の下に <assign> 要素を配置すれば、必要に応じてこれらのプロパティに値を割り当てることができます。以下に例を示します。
<process request="Demo.Loan.Msg.Application" response="Demo.Loan.Msg.Approval">
<context>
<property name="CreditRating" type="%Integer"/>
<property name="PrimeRate" type="%Numeric"/>
</context>
<sequence>
<call name="PrimeRate" target="Demo.Loan.WebOperations" async="0">
<request type="Demo.Loan.Msg.PrimeRateRequest">
</request>
<response type="Demo.Loan.Msg.PrimeRateResponse">
<assign property="context.PrimeRate" value="callresponse.PrimeRate"/>
</response>
</call>
...
</sequence>
...
</process>
上の BPL は最初の例の続きです。この例の <call> 要素は同期しており、<request> 要素と <response> 要素が両方とも含まれていることに注意してください。
この場合の <response> には、実行のコンテキストでオブジェクトの 2 つのプロパティを参照する <assign> 操作が記述されています。そのプロパティの 1 つは、汎用コンテキスト・オブジェクトのプロパティである context.PrimeRate です。もう 1 つのプロパティは、現在の <call> 要素に関連付けられた応答オブジェクト (ここでは Demo.Loan.Msg.PrimeRateResponse) のプロパティである callresponse.PrimeRate です。<assign> 操作は、<call> から返される PrimeRate プロパティの値を受け取り、その値を汎用コンテキスト・オブジェクトに配置します。
上に示す <sequence> 要素内の、<call> 要素の後は以下のようになります。
<call name="CreditRating" target="Demo.Loan.WebOperations" async="0">
<request type="Demo.Loan.Msg.CreditRatingRequest">
<assign property="callrequest.SSN" value='request.SSN'/>
</request>
<response type="Demo.Loan.Msg.CreditRatingResponse">
<assign property="context.CreditRating" value="callresponse.CreditRating"/>
</response>
</call>
上記の文は、基本要求 (request.SSN) の SSN プロパティを、現在の <call> 要素 (callrequest.SSN) によって作成される要求の SSN プロパティに割り当てます。この割り当ての後で、<call> 要素は要求を発行します。これは、タイプ Demo.Loan.WebOperations の同期呼び出しです。応答を受け取った <call> 要素は、<call> (callresponse.CreditRating) から返された CreditRating プロパティの値を取得して、汎用コンテキスト・オブジェクトのプロパティ (context.CreditRating) に配置します。
次の文は、整数値 1 を、ビジネス・プロセス (response.IsApproved) の基本応答オブジェクト内の IsApproved プロパティに割り当てます。この例では、IsApproved は、InterSystems IRIS の規則に応じてブーリアン値 (真または偽) になります。つまり、整数値 1 は真 (申込者が承認されたこと) を示し、0 は偽 (申込者が否認されたこと) を示します。
<assign name='IsApproved' property="response.IsApproved" value="1">
<annotation>
Copy IsApproved into the response object.
</annotation>
</assign>
以下の文は、計算値 (汎用コンテキスト・オブジェクト内の 2 つのプロパティを使用した式の結果) を、ビジネス・プロセス (response.InterestRate) の基本応答オブジェクト内の InterestRate プロパティに割り当てます。
<assign name='InterestRate'
property="response.InterestRate"
value="context.PrimeRate+1+(2*(1-(context.CreditRating/100)))">
<annotation>
Copy InterestRate into the response object.
</annotation>
</assign>
<assign> オペレーションのタイプ
BPL の <assign> 要素の構文は以下のように機能します。
-
property 属性は、オブジェクトと、割り当て操作のターゲットであるプロパティを識別します。
-
value 属性は、ターゲット・プロパティの値を指定します。これは、割り当て値を指定するために、実行時に評価される式になる場合もあります。<assign> 要素内の式は、そのビジネス・プロセスの <process> 要素で指定された言語を使用する必要があります。
-
BPL の <assign> オペレーションにはいくつかのタイプがあります。これらは、オプションの action 属性で指定します。action 属性には、以下の値を指定できます。
値 説明 append 一覧の最後にターゲット要素を追加します。 set (デフォルト) 新しい値にターゲット要素を設定します。 insert 集合に新しい値を挿入します。 remove 集合からターゲット要素を削除します。 clear ターゲット集合の内容を消去します。 デフォルト値の set を除くと、このようなアクションは、ほとんどがコレクション・プロパティに関係した割り当てを処理するためのものです。以下のテーブルは、さまざまな割り当てタイプについてまとめたものです。
プロパティのタイプ | action 属性の値 | key 属性の必要性 | 結果 |
---|---|---|---|
非コレクション | set | なし | プロパティは新しい値に設定されます。 |
配列 | clear | なし | 配列が消去されます。 |
配列 | remove | あり | key の要素が削除されます。 |
配列 | set | あり | key の要素が新しい値に設定されます。 |
リスト | append | なし | リストの末尾に要素が追加されます。 |
リスト | clear | なし | リストが消去されます。 |
リスト | insert | あり | key で指定した位置に要素が挿入されます。 |
リスト | remove | あり | key の要素が削除されます。 |
リスト | set | あり | key の要素が置換されます。 |
以下に、BPL <assign> 操作の各タイプについて詳しく説明します。
append (追加) 操作
append 操作では、リスト・プロパティの末尾にターゲット要素が追加されます。
set (設定) 操作
set 操作では、指定したプロパティの値が value 属性の値に設定されます。value 属性は、以下のように、式を含んでおり、それ自体が実行コンテキスト内のオブジェクトまたはオブジェクトのプロパティを参照できます。
<assign name='CopyResult' property='context.SSN' value='callresponse.SSN' />
ターゲット・プロパティが配列コレクションの場合、key 属性の値は配列内のアイテムを指定します。それ以外の場合、key 属性は無視されます。
ターゲット・プロパティがコレクションで、value 属性で以下のように同じタイプが指定されている場合は、コレクションの内容がターゲット・コレクションにコピーされます。
<assign name='CopyResults' property='context.List' value='callresponse.List' />
assign 要素のデフォルトのアクションは set 操作です。action が指定されていない場合、assign では set 操作が指定されます。
clear (消去) 操作
この操作は、コレクション・プロパティにのみ適用されます。clear 操作では、指定したコレクション・プロパティが消去されます。value 属性と key 属性は無視されます。ただし、<assign> 要素の BPL スキーマでは必要なので、文に value 属性を含める必要があります。
例えば、以下の文では、コレクション・プロパティ List が消去されます。
<assign name='ClearResults' property='context.List' action='clear' value='' />
insert (挿入) 操作
この操作は、リストのコレクション・プロパティにのみ適用されます。insert 操作では、指定したコレクション・プロパティに値を挿入します。key 属性が存在する場合は、key で指定された位置 (整数) の後ろに新しい値が挿入されます。指定がない場合、新しい項目は末尾に追加されます。
例えば、以下の例では、キー primary を使用して、配列コレクション・プロパティ Array に値を挿入します。
<assign name='Ins' property='context.Array'
action='insert'
key='primary'
value='request.Primary' />
remove (削除) 操作
この操作は、コレクション・プロパティにのみ適用されます。remove 操作では、指定したコレクション・プロパティからアイテムを削除します。value 属性は無視されます。ただし、<assign> 要素の BPL スキーマではこの属性が必須なので、文に value 属性を記述しておく必要があります。
ターゲット・プロパティが配列コレクションの場合、key 属性の値は配列内のアイテムを指定します。それ以外の場合、key 属性は無視されます。
例えば、以下では、キー abc を使用して、配列プロパティ Array から要素を削除します。
<assign name='Remove' property='context.Array' action='remove'
key='abc' value='' />
<assign> を使用したステータス変数の設定
status は %StatusOpens in a new tab 型のビジネス・プロセスの実行コンテキスト変数であり、成功または失敗を表します。
BPL ビジネス・プロセスのエラー処理は自動的に実行されます。BPL ソース・コードで status 値をテストまたは設定する必要はありません。ここでは、特殊な状況下で BPL ビジネス・プロセスを終了しなければならない場合に備えて、status 値が設けられています。
BPL ビジネス・プロセスが開始されると、status には成功を示す値が自動的に割り当てられます。status に成功値が割り当てられているかどうかを確認するには、ObjectScript ではマクロ $$$ISOK(status) を使用します。このテストで True 値が返された場合、status には成功値が格納されています。
BPL ビジネス・プロセスの実行中に status が失敗値を受け取ると、そのビジネス・プロセスは即座に終了し、該当するテキスト・メッセージがイベント・ログに書き込まれます。この処理は、status がどのような状況で失敗値を受け取ったかにかかわらず実行されます。したがって、status に失敗値を設定すれば、BPL ビジネス・プロセスをいつでも正常に終了することができます。
<assign> 要素を使用すれば、status に失敗値を設定できます。その場合、通常は、まず <if> 要素を使用して以前のアクティビティの結果を確認します。次に、<true> 要素または <false> 要素内で、失敗条件が存在するとき、<assign> を使用して status に失敗値を設定します。
BPL ビジネス・プロセスでは、<process> 内であればどこでも status を使用できます。status を参照するための構文は、%StatusOpens in a new tab 型の変数の場合と同じです。つまり status となります。