XML 仮想ドキュメントの DOM スタイル・パスの指定

ノードの取得または設定 (基本的なパス)

XML 仮想ドキュメントには、ルート・ノード、要素、テキスト・ノード、コメント、および処理手順の 5 種類のノードがあります。ルート・ノードおよびいずれの要素も、あらゆるタイプの子ノードを持つことができます。その他の種類のノードは、子ノードを持つことができません。また、属性はノードではありません。

以下のテーブルは、XML 仮想ドキュメントのノードの多くを取得または設定するための、基本的な DOM スタイル・パスを示しています。同じタイプまた同じ名前を持つ複数のノードがある場合で、最初のノードを使用したくない場合には、次の節を参照してください。

また、これらのパスは、より複雑な DOM スタイル・パスを作成する場合にも使用します (これについては、後の項で説明します)。

以下の XML ドキュメントについて考えてみましょう。

<?xml version="1.0" ?>
<Patient xmlns='http://myapp.com'>Sample text node
    <!--Sample comment-->
    <!--Another comment-->
    <Name>Jane Doe</Name>
    <Address>
        <Street>100 Blank Way</Street>
    </Address>
</Patient>

以下のテーブルに、このドキュメントのパスの例をいくつか示します。

ここで、以下のコードのみを含むデータ変換を使用するとします。

 set status=target.SetValueAt("892 Broadway","/Patient/Address/Street")
 if 'status {do $system.Status.DisplayError(status) quit}
 set status=target.SetValueAt("Dr. Badge","/Patient/Doctor/Name")
 if 'status {do $system.Status.DisplayError(status) quit}

これらのパスの 1 つは既に存在し、もう 1 つは存在しませんが、両方のパスが有効であることに注意してください。この変換を使用すると、新しいドキュメントは以下のようになります。

<?xml version="1.0" ?>
<Patient xmlns='http://myapp.com'>Sample text node
   <!--Sample comment-->
   <!--Another comment-->
   <Name>Jane Doe</Name>
   <Address>892 Broadway</Address>
   <Doctor>
      <Name>Dr. Badge</Name>
   </Doctor>
</Patient>

パス設定時の混合コンテンツの使用

ノードで値を設定するために setValueAt() を使用する場合、混合コンテンツ (要素とテキスト・ノードが混在して構成された値) で構成された値を指定できます。以下に例を示します。

 set mixed="SOME TEXT<HOMETOWN>BELMONT</HOMETOWN>"
 set status=target.SetValueAt(mixed,"/Patient/Address/Street")

以下の表は、異なる種類のノードのそれぞれに値を設定するとき Ensemble がどのように値を処理するかを説明しています。

属性はノードではないことに注意してください。

基本的なパス修飾子の使用

上記の節に示した基本的なパスの最後に、以下の基本的なパス修飾子を追加できます (例外についても説明します)。基本的なパスのいずれかを使用するのと同じ方法で、結果のパスを使用することが可能です。

後の節で示す各種のパス修飾子を使用することで、ノードを挿入したり追加したりできます。(“パス修飾子のサマリ” も参照してください。)

以下の XML ドキュメントについて考えてみましょう。

<?xml version="1.0" ?>
<Patient xmlns='http://myapp.com'>
    <!--Sample comment-->
    <!--Another comment-->
    Sample text node
    <Name>Fred Williams</Name>
    <FavoriteColors>
      <FavoriteColor>Red</FavoriteColor>
      <FavoriteColor>Green</FavoriteColor>
    </FavoriteColors>
    <Doctor>
      <Name>Dr. Arnold</Name>
    </Doctor>
</Patient>

以下のテーブルに、このドキュメントのパスの例をいくつか示します。

Full() 関数の使用

要素を参照するパス (基本的なパス、または基本的な修飾子を使用するパスのいずれか) の場合、要素の開始タグおよび終了タグを取得することもできます。そのためには、パスの最後に full() を追加します。

値を設定する場合は、full() 関数が使用できます。DTL 内では、これが [追加] アクションを使用するデータ変換内でしか許可されません。後述する “XML 仮想ドキュメントの割り当てアクション” を参照してください。

以下の XML ドキュメントについて考えてみましょう。

<?xml version="1.0" ?>
<Patient xmlns='http://myapp.com'>
    <Name>Jack Brown</Name>
    <Address>
        <Street>233 Main St</Street>
    </Address>
</Patient>

以下のテーブルに、このドキュメントのパスの例をいくつか示します。

ルート・ノードの場合、full() 関数は暗黙的に示されます。つまり、以下の 2 つのパスは同等です。

/
/full()

XML 属性の値の取得または設定

属性の値にアクセスするには、以下の DOM スタイル・パスのいずれかを使用します。この節の以降の部分では、element_reference は完全な DOM スタイル・パスです。

角かっこを省略することもできます。

例えば、以下の XML ドキュメントについて考えてみましょう。

<?xml version="1.0" ?>
<Patient MRN='000111222' DL='123-45-6789' xmlns='http://myapp.com'>
    <Name>Liz Jones</Name>
</Patient>

以下のテーブルに、このドキュメントのパスの例をいくつか示します。

ノードを挿入または追加するためのパス修飾子の使用

ノードを挿入または追加するには、以下のパス修飾子を基本的なパスの最後に追加します。ここに示すパス修飾子は、値を設定する場合にのみ使用してください。

いくつかの追加オプションについて、次の節も参照してください。

[~n]

指定されたコンテキストにおいて、基本的なパスの参照先の項目のインスタンスを、その項目の n 番目のインスタンスの直前に挿入します。上書きは一切されません。詳細は、以下のテーブルを参照してください。

この項の以降の部分では、n は整数です。

パスの例	動作
/Patient/Episode[~5]	<Patient> 内に存在する 5 番目の <Episode> 要素の前に、新しい <Episode> 要素を挿入します。 <Patient> に 5 番目の <Episode> 要素が含まれていない場合、Ensemble によってパディングが行われ、空の <Episode> 要素が作成されるため、挿入された <Episode> が 5 番目の <Episode> になります。新しく挿入される要素はすべて、<Patient> 要素の最後に挿入されます。 パスが中間の存在しない要素を参照する場合、Ensemble によってそれらが作成されます。
/Patient/element(Episode)[~5]	<Patient> 内に存在する 5 番目の要素の前に、<Episode> 要素を挿入します。 <Patient> に 5 番目のどのタイプの要素も含まれていない場合、このパスは無効になります。element() 関数によって、パディングのために空の要素が生成されることはありません。
/Patient/[~5]	指定できません。挿入する要素の種類に関する情報がないためです。
/Patient/element()[~5]

例えば、以下の XML ドキュメントについて考えてみましょう。

<?xml version="1.0" ?>
<Patient xmlns='http://myapp.com'>
    <Name>Betty Hodgkins</Name>
    <FavoriteColors>
        <FavoriteColor>Purple</FavoriteColor>
    </FavoriteColors>
</Patient>

また、データ変換内の以下のコードについても考えてみましょう。

 set status=target.SetValueAt("INSERTED COLOR","/Patient/FavoriteColors/FavoriteColor[~4]")
 if 'status {do $system.Status.DisplayError(status) quit}

このコード行によって、元のドキュメントが以下のように変換されます。

<?xml version="1.0" ?>
<Patient>
    <Name>Betty Hodgkins</Name>
    <FavoriteColors>
        <FavoriteColor>Purple</FavoriteColor>
        <FavoriteColor/>
        <FavoriteColor/>
        <FavoriteColor>INSERTED COLOR</FavoriteColor>
    </FavoriteColors>
</Patient>

もう 1 つの例として、以下の XML ドキュメントについて考えてみましょう。

<Patient xmlns='http://myapp.com'>
    <Name>Colin McMasters</Name>
    <Address>
        <Street>102 Windermere Lane</Street>
    </Address>
</Patient>

また、データ変換内の以下のコードについても考えてみましょう。

 set status=target.SetValueAt("INSERTED ADDRESS","/Patient/Address/Street[~2]")
 if 'status {do $system.Status.DisplayError(status) quit}

このコード行によって、元のドキュメントが以下のように変換されます。

<?xml version="1.0" ?>
<Patient>
    <Name>Colin McMasters</Name>
    <Address>
        <Street>102 Windermere Lane</Street>
        <Street>INSERTED ADDRESS</Street>
    </Address>
</Patient>

基本的なパスの参照先の項目のインスタンスを、指定された親の (新しい) 最後のノードとして追加します。上書きは一切されません。

パスの例	動作
/Patient/Episode[~]	<Patient> 内の最後のノードとして、新しい <Episode> 要素を追加します。パスが中間の存在しない要素を参照する場合、Ensemble によってそれらが作成されます。
/Patient/element(Episode)[~]	<Patient> 内の最後のノードとして、<Episode> 要素を追加します。パスが中間の存在しない要素を参照する場合、このパスは無効になります。
/Patient/[~]	指定できません。追加する要素の種類に関する情報がないためです。
/Patient/element()[~]

例えば、以下はデータ変換におけるコード要素の一部を示しています。

 set status=target.SetValueAt("orange","/Patient/FavoriteColors/Color[~]")
 if 'status {do $system.Status.DisplayError(status) quit}
 set status=SetValueAt("pink","/Patient/FavoriteColors/Color[~]")
 if 'status {do $system.Status.DisplayError(status) quit}

これによって、2 つの <Color> が新しい子要素として <FavoriteColors> 要素に追加されます。<FavoriteColors> 要素が存在しない場合は、Ensemble によって作成されます。

“パス修飾子のサマリ” も参照してください。

element() 関数の使用

値を取得または設定する場合、以下のテーブルに示すように、element() 関数を使用できます。

要素の位置の取得

要素の位置を取得するには、以下の構文を使用します。

要素の数の取得

要素の数を取得するには、以下の構文を使用します。

/[*] 以外のすべての場合に、角かっこを省略することができます。Ensemble では、last() 関数 (count() 関数と同等) および node-last() 関数 (node-count() 関数と同等) もサポートされています。同様の last() 関数が用意されている XPATH に慣れている場合は、last() および node-last() を使用することもできます。

その他のメタデータへのアクセス

XML 仮想ドキュメントのその他のメタデータにアクセスするには、以下の関数を使用します。これらの関数は、パスの最後でのみ使用できます。

パス修飾子のサマリ

以下の表に、DOM スタイル・パスのパス修飾子のサマリを示します。

ネームスペースを使用するドキュメントのバリエーション

ドキュメントで XML ネームスペースが使用されている場合、ネームスペース内の要素または属性ごとに、そのパスのセクションをネームスペース接頭語とそれに続くコロン (:) を含めるように変更する必要があります。ネームスペース接頭語は、以下のいずれかです。

• 対応する XML スキーマをロード済みの場合は、このドキュメントで前述した “XML ネームスペース・トークン” での説明に従って、ネームスペース・トークンを使用します。例 ：element_name ではなく、$2:element_name を使用

• XML スキーマをロードしていない場合、ドキュメントで指定されているとおりのネームスペース接頭語を使用します。例 ：s01:Patient

• ネームスペースを無視するには、ワイルドカード * を使用します。例 ：*:Patient

別のオプションとして、ドキュメント内のすべてのネームスペースを無視することもできます。そのためには、パスを / でなく、ワイルドカード *:/ で始めます。

例 ：*:/Patient/@MRN

パスの値を設定する場合は、そのパスにワイルドカードを使用することはできません。

ターミナルでの DOM スタイル・パスのテスト

特に、構文に精通している場合は、仮想ドキュメント・プロパティ・パスをビジネス・プロセスやデータ変換などで使用する前にターミナルでテストできると便利です。DOM スタイル XML パスに対してこれを行うには、ターミナルまたはテスト・コードで次の手順を実行します。

1. 適切な XML ドキュメントのテキストを含む文字列を作成します。

2. EnsLib.EDI.XML.DocumentOpens in a new tab の ImportFromString() メソッドを使用してこの文字列から XML 仮想ドキュメントのインスタンスを作成します。

3. このインスタンスの GetValueAt() および SetValueAt() メソッドを使用します。

以下のメソッドがこれらのステップを実行します。

ClassMethod TestDOMPath()
{
    set string="<Patient xmlns='http://myapp.com'>"
    _"<Name>Jolene Bennett</Name>"
    _"<Address><Street>899 Pandora Boulevard</Street></Address>"
    _"</Patient>"
    set target=##class(EnsLib.EDI.XML.Document).ImportFromString(string,.status)
    if 'status {do $system.Status.DisplayError(status)  quit}
    
    set pathvalue=target.GetValueAt("/Patient/Name",,.status)
    if 'status {do $system.Status.DisplayError(status)  quit}
    write pathvalue
}

このメソッドの出力を以下に示します。

ENSDEMO>d ##class(Demo.CheckPaths).TestDOMPath()
Jolene Bennett

GetValueAt() のその他のオプションは、後述する “pFormat 引数” を参照してください。