%LOOKUPxx (查閱陣列元素)

線上編輯

%LOOKUP(arg : array | keyed_array_DS {: start_index {: number_of_elements}})
%LOOKUPLT(arg : array  {: start_index {: number_of_elements}})
%LOOKUPGE(arg : array  {: start_index {: number_of_elements}})
%LOOKUPGT(arg : array  {: start_index {: number_of_elements}})
%LOOKUPLE(arg : array  {: start_index {: number_of_elements}})

下列函數會傳回陣列中符合 arg之項目的陣列索引。 %LOOKUP 也可以用來傳回索引陣列資料結構中項目的陣列索引。

%LOOKUP: 完全相符。
%LOOKUPLT: 最接近 arg 但小於 arg的值。
%LOOKUPLE: 完全相符，或最接近 arg 但小於 arg的值。
%LOOKUPGT: 最接近 arg 但大於 arg的值。
%LOOKUPGE: 完全相符，或最接近 arg 但大於 arg的值。

如果沒有值符合指定的條件，則會傳回零。傳回的值為不帶正負號的整數格式 (類型 U)。

可能有多個元素符合指定的條件。在下列討論中，假設遞增和遞減陣列的值如下。


           +---+---+---+---+---+---+---+
           | 1 | 2 | 3 | 4 | 5 | 6 | 7 |
-----------+---+---+---+---+---+---+---+
ASCEND     | A | C | C | C | E | E | G |
-----------+---+---+---+---+---+---+---+
DESCEND    | G | E | E | E | C | C | A |
-----------+---+---+---+---+---+---+---+

對於 %LOOKUP、%LOOKUPLE 或 %LOOKUPGE ，如果有多個元素等於搜尋引數，則會傳回第一個相符元素的索引。例如，如果搜尋引數為 C ，則這些內建函數將針對遞增陣列傳回 2 ，針對遞減陣列傳回 5。
對於遞增陣列的 %LOOKUPLE ，如果沒有元素等於搜尋引數，則內建函數會傳回小於搜尋引數之最後一個元素的索引。例如，如果搜尋引數為 D ，則 %LOOKUPLE 會傳回 4。
對於遞減陣列的 %LOOKUPLE ，如果沒有元素等於搜尋引數，則內建函數會傳回小於搜尋引數之第一個元素的索引。例如，如果搜尋引數為 D ，則 %LOOKUPLE 會傳回 5。
對於遞增陣列的 %LOOKUPGE ，如果沒有元素等於搜尋引數，則內建函數會傳回大於搜尋引數之第一個元素的索引。例如，如果搜尋引數為 D ，則 %LOOKUPGE 會傳回 5。
對於遞減陣列的 %LOOKUPGE ，如果沒有元素等於搜尋引數，則內建函數會傳回大於搜尋引數之最後一個元素的索引。例如，如果搜尋引數為 D ，則 %LOOKUPGE 會傳回 4。
對於遞增陣列的 %LOOKUPLT ，內建函數會傳回小於搜尋引數之最後一個元素的索引。例如，如果搜尋引數是 D ，則 %LOOKUPLT 會傳回 4。
對於遞減陣列的 %LOOKUPLT ，內建函數會傳回小於搜尋引數之第一個元素的索引。例如，如果搜尋引數為 D ，則 %LOOKUPLT 會傳回 5。
對於遞增陣列的 %LOOKUPGT ，內建函數會傳回大於搜尋引數之第一個元素的索引。例如，如果搜尋引數為 D ，則 %LOOKUPGT 會傳回 5。
對於遞減陣列的 %LOOKUPGT ，內建函數會傳回大於搜尋引數之最後一個元素的索引。例如，如果搜尋引數為 D ，則 %LOOKUPGT 會傳回 4。

搜尋開始於索引 start_index ，並繼續搜尋 number_of_elems 元素。依預設，會搜尋整個陣列。

第二個參數可以是格式為 ARRAY_NAME 的純量陣列。對於 %LOOKUP ，它也可以是格式為 ARRAY_DS_NAME (*). SUBFIELD_NAME 的索引陣列資料結構。

若要搜尋陣列資料結構，請以索引 (*) 指定資料結構名稱，然後指定要用作搜尋索引鍵的子欄位。例如，若要在陣列資料結構 INFO 的 CODE 子欄位中搜尋值 'XP2' ，請指定 'XP2' 作為第一個參數，並指定 INFO (*). CODE 作為第二個參數。 (*) 索引之前的完整名稱部分必須代表陣列，而 (*) 之後的完整名稱部分必須代表純量子欄位或純量的索引陣列。

前兩個參數可以具有任何類型，但必須具有相同的類型。對於索引資料結構陣列，第一個參數必須具有與索引鍵相同的類型。它們不需要具有相同的長度或小數位數。第三和第四個參數必須是具有零小數位數的非浮點數值。

對於 %LOOKUPLT、%LOOKUPLE、%LOOKUPGT 及 %LOOKUPGE ，陣列必須使用關鍵字 ASCEND 或 DESCEND 定義。除非以 ALTSEQ (*NONE) 定義 arg 或陣列，否則會使用 ALTSEQ 表格。

未在 %LOOKUP 作業之後設定內建函數 %FOUND 及 %EQUAL。

%LOOKUPxx 內建函數會對已排序的陣列 (已指定 ASCEND 或 DESCEND 關鍵字的陣列) 使用二進位搜尋。

附註: 與 LOOKUP 作業碼不同， %LOOKUP 僅適用於陣列。若要查閱表格中的值，請使用 %TLOOKUP 內建函數。

如需相關資訊，請參閱：

圖 1. 具有純量陣列的 %LOOKUPxx

 *..1....+....2....+....3....+....4....+....5....+....6....+....7...+....
 /FREE
   arr(1) = 'Cornwall';
   arr(2) = 'Kingston';
   arr(3) = 'London';
   arr(4) = 'Paris';
   arr(5) = 'Scarborough';
   arr(6) = 'York';

   n = %LOOKUP('Paris':arr);
   // n = 4

   n = %LOOKUP('Thunder Bay':arr);
   // n = 0 (not found)

   n = %LOOKUP('Kingston':arr:3);
   // n = 0 (not found after start index)

   n = %LOOKUPLE('Paris':arr);
   // n = 4

   n = %LOOKUPLE('Milton':arr);
   // n = 3

   n = %LOOKUPGT('Sudbury':arr);
   // n = 6

   n = %LOOKUPGT('Yorks':arr:2:4);
   // n = 0 (not found between elements 2 and 5)
 /END-FREE

圖 2. 具有陣列資料結構的 %LOOKUP

D emps            DS                  QUALIFIED DIM(20)
D    name                       25A   VARYING
D    id                          9S 0
D numEmps         S             10I 0
 /FREE
   emps(1).name = 'Mary';
   emps(1).id = 00138;
   emps(2).name = 'Patrick';
   emps(2).id = 10379;
   emps(3).name = 'Juan';
   emps(3).id = 06254;
   numEmps = 3;

   // Search for employee 'Patrick'
   n = %lookup('Patrick' : emps(*).name : 1 : numEmps);
   // n = 2

   // Search for the employee with id 06254
   n = %lookup(06254 : emps(*).id : 1 : numEmps);
   // n = 3

   // Search for employee 'Bill' (not found)
   n = %lookup('Bill' : emps(*).name : 1 : numEmps);
   // n = 0