リスト/クエリ メソッド

この記事には、以下のトピックが含まれています。
casm173
この記事には、以下のトピックが含まれています。
リストの操作には 2 つの方法が使用できます。 1 つは、リスト ハンドルを使用してサーバ側のリストを参照およびクエリします。もう 1 つは、SQL に似た選択操作を実行します。
静的リストを参照する必要がある場合は、リスト ハンドルを返すメソッドを使用します。 これらのメソッドは、非常に大きなリストを操作するときに特に役立ちます。 たとえば、アプリケーションで、連絡先が全部で 10,000 個含まれているテーブル全体を対象とした操作を行う必要があるとします。 一度に 10,000 個すべての値をダウンロードすると、許容範囲を超えたパフォーマンス遅延が発生する可能性があります(実際には、システムがこの状況を防ぎます。「Where 節」を参照)。 しかし、リスト ハンドルを使用すると、クエリする行の範囲を選択できます。
リスト ハンドルを使用するときの主な欠点は、メソッドをコールする回数が増えることです。 少なくとも、以下のように 2 回または 3 回のコールが必要になります。
  • ハンドルを取得するコール
  • 値を取得するコール(1 回または 2 回)
  • リストを解放するコール
リモート メソッド コールの回数と返されるデータの予想量を比較検討する必要があります。
CA SDM では、1 つのリストから返されるデータの量に制限があります。 詳細については、「Where 節」を参照してください。
doSelect
doSelect メソッドでは、以下のパラメータを使用します。
パラメータ
タイプ
説明
SID
整数
ログインにより取得したセッションを指定します。
objectType
文字列
クエリするオブジェクト タイプ(ファクトリ)を指定します。
whereClause
文字列
(オプション)クエリのWhere節を指定します。
maxRows
整数
返される行の最大数を指定します。 -1を指定するとすべての行が返されます。
注:
指定した整数に関係なく、CA SDM では 1 コールにつき最大 250 行が返されます。
attributes
String[]
値をフェッチする属性のリストを指定します。 ドット付きの属性を使用することができます。 このフィールドが空の場合は、値に基づく属性がすべて返されます。 これらの属性はmajic定義ファイルでLOCALと定義することはできません。 LOCAL属性は一時的で、データベースに保存されません。
説明
指定したオブジェクト テーブルに対して SQL に似た選択操作が実行されます。 指定したWhere節に一致するオブジェクトから属性をフェッチして、必要な1つ以上の属性を返します。
戻り値
一連の <UDSObject> エレメント。 以下のフォーマットが適用されます。
<UDSObjectList> <UDSObject> <Handle> <Attributes> <AttributeNameA> <AttributeValueA0> <AttributeValueA1> <AttributeNameB> <AttributeValueB0> ...
XML エレメント
タイプ
説明
N/A
ハンドルおよびリクエストされた属性値を含む、標準UDSObjectエレメントを示します。
<UDSObjectList>
シーケンス
<Handle> エレメント、および一連の <Attributes> を含みます。
たとえば、以下のようなメソッドを使用するとします。
String[] myArray = ["last_name", "first_name"] doSelect(mySID, "cnt", "last_name LIKE 'J%'", 2, myArray)
戻り値は以下のようになります。
<UDSObjectList> <UDSObject> <Handle>cnt:555A043EDDB36D4F97524F2496B35E75</Handle> <Attributes> <AttributeName>last_name</AttributeName> <AttributeValue>Johnson</AttributeValue> <AttributeName>first_name</AttributeName> <AttributeValue>Carol</AttributeValue> </Attributes> </UDSObject> <UDSObject> <Handle>cnt:555A043EDDB36D4F97524F2496B35E76</Handle> <Attributes> <AttributeName>last_name</AttributeName> <AttributeValue>Jones</AttributeValue> <AttributeName>first_name</AttributeName> <AttributeValue>Ron</AttributeValue> </Attributes> </UDSObject> </UDSObjectList>
doQuery
doQuery メソッドでは、以下のパラメータを使用します。
パラメータ
タイプ
説明
SID
整数
ログインにより取得したセッションを指定します。
ObjectType
文字列
クエリするオブジェクト タイプ(ファクトリ)を指定します。
WhereClause
文字列
(オプション)クエリのWhere節を指定します。
説明
指定したオブジェクト タイプに対して SQL に似た選択操作が実行されます。 また、クエリによって返された行のリストを指す
リスト ハンドル
も返されます。各行は、指定した
Where 節に一致した CA SDM オブジェクトを表しています。 コール元は getListValues() を使用してリストの行の値をフェッチできます。
Where 節の詳細については、「Where 節」を参照してください。
オブジェクト リストは CA SDM サーバに保存され、システムのリソースを消費します。 コール元は、freeListHandles() でリストを解放する必要があります。 メモリ内にリストが残っていると、プロセスに対するメモリが増加して 2 GB の制限を超過し、メモリ リークが発生して、システム障害を引き起こす可能性があります。
この関数によって作成されたリストは均質です。つまり、オブジェクトはすべて同じタイプで、静的です。したがって、オブジェクトに対するデータ変更によって、最初の Where 節に一致しなくなった場合でも、リストは変更されません。
戻り値
freeListHandle() で解放する必要のあるリスト ハンドル。
XML エレメント
タイプ
説明
<listHandle>
整数
リスト ハンドルを示します。
<listLength>
整数
生成されたリストの長さを示します。
getListValues
getListValues メソッドでは、以下のパラメータを使用します。
パラメータ
タイプ
説明
SID
整数
ログインにより取得したセッションを指定します。
ListHandle
整数
前のコールで取得したリスト ハンドルを指定します。
StartIndex
整数
リスト内のフェッチ開始位置を指定します。
EndIndex
整数
リスト内のフェッチ終了位置を指定します。 -1 を指定すると、StartIndex 以降のすべての行がフェッチされます。
注:
指定した整数に関係なく、Web サービスでは 1 コールにつき最大 250 行が返されます。
AttributeNames
String[]
値をフェッチする 1 つ以上の属性名の配列を指定します。
説明
リスト内の一定範囲内のオブジェクトの属性値が返されます。 以下に例を示します。
< UDSObjectList > <UDSObject> <Handle> <Attributes> <AttributeName0> <AttributeName1>
戻り値
このメソッドは、以下の戻り値を返します。
XML エレメント
タイプ
説明
<UDSObjectList>
シーケンス
一連の <UDSObject> エレメントを含む外部エレメントを示します。
N/A
<Handle> エレメントと一連の <Attributes> を含みます。
freeListHandles
freeListHandles メソッドでは、以下のパラメータを使用します。
パラメータ
タイプ
説明
SID
整数
ログインにより取得したセッションを指定します。
Handles
Integer[]
解放するリスト ハンドルの配列を指定します。
説明
サーバ側のリスト用リソースが解放され、リスト ハンドルが無効になります。 このメソッドは、リスト参照が不要になったときに、必ずコールする必要があります。
戻り値
なし。
getRelatedList
getRelatedList メソッドでは、以下のパラメータを使用します。
パラメータ
タイプ
説明
SID
整数
ログインにより取得したセッションを指定します。
ObjectHandle
文字列
オブジェクト ハンドルを指定します。
ListName
文字列
オブジェクトのリスト タイプの属性名を指定します。
説明
オブジェクトのリスト(QREL または BREL)属性のリスト ハンドルが返されます。 たとえば、リクエスト オブジェクトには「children」という名前の関連リストがあり、これは子リクエストのリストです。 別の例として、リクエストのアクティビティ ログ(「act_log」または「act_log_all」)もあります。
オブジェクトのリスト属性に関する情報を取得するには、オブジェクト スキーマ(majic)のマニュアルを参照するか、getObjectTypeInformation() を使用します。
戻り値
以下の値が返されます。
XML エレメント
タイプ
説明
<listHandle>
整数
リスト ハンドルを示します。
<listLength>
整数
生成されたリストの長さを示します。
getRelatedListValues
getRelatedListValues メソッドでは、以下のパラメータを使用します。
パラメータ
タイプ
説明
SID
整数
ログインにより取得したセッションを指定します。
objectHandle
文字列
オブジェクト ハンドルを指定します。
listName
文字列
オブジェクトのリスト タイプの属性名を指定します。
numToFetch
整数
返される行の最大数を指定します。
0 にすることはできません。
-1 を指定するとすべての行が返されます。
注:
指定した整数に関係なく、Web サービスでは 1 コールにつき最大 250 行を返すことができます。
attributes
String[]
値をフェッチする1つ以上の属性名の配列を指定します。 ドット付きの名前を使用できます。
getRelatedListValuesResult
String Holder
返されたデータをキャプチャするための String Holder オブジェクトを指定します。
numRowsFound
Integer Holder
返されたデータをキャプチャするための Integer Holder オブジェクトを指定します。
説明
特定のオブジェクトに関連したリストの値が返されます。 リストは QREL または BREL として定義する必要があります。 LREL タイプをクエリするには、LREL メソッドを使用します。
たとえば、リクエスト オブジェクトには「children」という名前の関連リストがあり、これは子リクエストのリストです。 このメソッドは、getRelatedList() に代わるものですが、リスト ハンドルを使用しません。 戻り値の形式は以下に示すとおり、getListValues() に似ています。
<numRowsFound> < UDSObjectList > <UDSObject> <Handle> <AttributeName0> <AttributeName1>
オブジェクト スキーマ(majic)を使用して、オブジェクト リスト属性の情報を取得できます。 このメソッドの代わりに getObjectTypeInformation() を使用することができます。
戻り値
このメソッドは、以下の戻り値を返します。
XML エレメント
タイプ
説明
<getRelatedListValuesResult>
N/A
一連の<UDSObject> エレメントを含む外部エレメント <UDSObjectList> を示します。 各 <UDSObject> エレメントには、1 つの <Handle> エレメントおよび 0 個以上の <AttributeNameX> エレメントが含まれます。
<numRowsFound>
整数
クエリしたリストの全行数を示します。
注:
行数の合計は、必ずしも返された行数ではありません。
getPendingChangeTaskListForContact
getPendingChangeTaskListForContact メソッドでは、以下のパラメータを使用します。
パラメータ
タイプ
説明
SID
整数
ログインにより取得したセッションを指定します。
contactHandle
文字列
連絡先のハンドルを指定します。
説明
連絡先に割り当てられた、すべての「保留中」変更要求ワークフロー タスクを表すリスト ハンドルが返されます。 「保留中」タスクはアクティブなワークフロー タスクで、更新を許可するステータスを持っています。
戻り値
以下の値が返されます。
XML エレメント
タイプ
説明
<listHandle>
整数
リスト ハンドルを示します。
<listLength>
整数
生成されたリストの長さを示します。
getPendingIssueTaskListForContact
getPendingIssueTaskListForContact メソッドでは、以下のパラメータを使用します。
パラメータ
タイプ
説明
SID
整数
ログインにより取得したセッションを指定します。
contactHandle
文字列
連絡先のハンドルを指定します。
説明
連絡先に割り当てられた、すべての「保留中」案件タスクを表すリスト ハンドルが返されます。 「保留中」タスクはアクティブなタスクで、更新を許可するステータスを持っています。
戻り値
以下の値が返されます。
XML エレメント
タイプ
説明
<listHandle>
整数
リスト ハンドルを示します。
<listLength>
整数
生成されたリストの長さを示します。
getNotificationsForContact
getNotificationsForContact メソッドでは、以下のパラメータを使用します。
パラメータ
タイプ
説明
SID
整数
ログインにより取得したセッションを指定します。
contactHandle
文字列
連絡先のハンドルを指定します。
queryStatus
整数
(オプション)通知のターゲットを指定します。
説明
連絡先に対する通知(「lr」オブジェクト)のリストが返されます。
通知の特定のステータスを
queryStatus
フィールドでクエリできます。たとえば、クリアされていないメッセージのみを返すときに便利です。 使用可能な
queryStatus
の値は以下のとおりです。
  • -1
    - すべての通知をフェッチする
  • 0
    - クリアされていない通知(ステータス値が 7 より小さい通知)をフェッチする
  • 1
    - クリアされた通知(ステータス値が 7、8、または 9 の通知)をフェッチする
戻り値
以下の値が返されます。
XML エレメント
タイプ
説明
<listHandle>
整数
リスト ハンドルを示します。
<listLength>
整数
生成されたリストの長さを示します。