SpmiNext值子常式

用途

傳回一組統計資料中的第一個 SpmiStatVals 結構，或根據從 SpmiStatVals 結構的資料欄位中擷取的資料值類型，傳回一組統計資料中的下一個 SpmiStatVals 結構。

程式庫

SPMI 程式庫 (libSpmi.a)

語法

#include sys/Spmidef.h

struct SpmiStatVals*SpmiNextValue( StatSet, StatVal, value)
struct SpmiStatSet *StatSet;
struct SpmiStatVals *StatVal;
float *value;

說明

SpmiNext值 子常式會在一次呼叫中同時傳回 SpmiGet值 (從 SpmiStatVals 結構取得解碼值) ，而不是對 SpmiFirstVals 子常式 / SpmiNextVals 子常式 (取得第一個或下一個 SpmiStatVals 結構) 發出子常式呼叫。 如果 StatVal 參數是 NULL ，則此子常式呼叫會傳回屬於 StatSet 參數之第一個 SpmiStatVals 結構的指標。 如果 StatVal 參數不是 NULL ，則會傳回下一個 SpmiStatVals 結構，並以 StatVal 參數所識別的結構作為現行結構。 在 value 引數所指向的欄位中，會解碼並傳回對應於所傳回 SpmiStatVals 結構的資料值。 在解碼資料值時，子常式會執行下列動作:

• 判定資料欄位的格式為 SiFloat 或 SiLong ，並擷取資料值以進一步處理。
• 將資料值判定為類型 SiQuantity 或類型 SiCounter ，並執行這裡列出的其中一個動作:
  • 如果資料值類型為 SiQuantity，則子常式會傳回 SpmiStatVals 結構的 val 欄位。
  • 如果資料值類型為 SiCounter，則子常式會傳回 SpmiStatVals 結構的 val_change 欄位值，除以自前次針對這組統計資料要求資料值以來所經歷的秒數。

此子常式是 Performance Aide for AIX® 授權產品的伺服器選項的一部分。

參數

StatSet

指定指標，指向 SpmiCreateStatSet 子常式 呼叫所建立之 SpmiStatSet 類型的有效結構。

StatVal

指定 NULL 指標或指標，指向 SpmiPathAddSetStat Subroutine 呼叫所建立或前一個 SpmiNextValue 子常式呼叫所傳回之 SpmiStatVals 類型的有效結構。 如果 StatVal 是 NULL ，則會傳回屬於 StatSet 所指向之統計資料集的第一個 SpmiStatVals 指標。

value根據從所傳回 SpmiStatVals 結構的資料欄位中擷取的資料值類型，用來傳回解碼值的指標。

回覆值

如果成功， SpmiNext值 子常式會傳回 SpmiStatVals 結構的指標。 如果不成功，子常式會傳回空值。

如果 StatVal 參數為:

NULL 傳回屬於 StatSet 參數的第一個 SpmiStatVals 結構。

非空值 傳回 StatVal 參數所識別結構之後的下一個 SpmiStatVals 結構，並且使用值參數根據從所傳回 SpmiStatVals 結構的資料欄位中擷取的資料值類型來傳回解碼值。

錯誤碼

所有 SPMI 子常式都使用外部變數來提供錯誤資訊。 若要存取這些變數，應用程式必須定義下列外部變數:

• extern char SpmiErrmsg[];
• extern int SpmiErrno;

如果子常式傳回沒有錯誤，則 SpmiErrno 變數會設為 0 ，且 SpmiErrmsg 字元陣列是空的。 如果偵測到錯誤， SpmiErrno 變數會傳回錯誤碼，如 sys/Spmidef.h 檔案中所定義，且 SpmiErrmsg 變數包含以英文說明錯誤原因的文字。

程式設計注意事項

SpmiNextValue 子常式會維護內部狀態資訊，因此可以在不遍訪資料結構鏈結清單的情況下，完成從狀態集擷取下一個資料值。 統計資料資訊會針對每一個處理程序保持個別，但由處理程序的所有執行緒共用。

如果從多個執行緒存取子常式，則狀態資訊無用，且失去效能優點。 如果程式同時存取兩個以上狀態集，則也是如此。 若要受益於 SpmiNextValue 子常式的效能優點，程式應該先從一個統計資料集依序擷取所有值，然後再從下一個統計資料集擷取值。

如果已知 SpmiStatVals 指標，則子常式的實作可讓程式從狀態集中的任何點開始擷取資料值。 這樣做會導致鏈結清單遍訪。 如果 SpmiNextValue 的後續呼叫使用從第一個及後續呼叫傳回的值作為其第二個引數，則可以避免遍訪鏈結清單。

請注意，成功 SpmiNext值 呼叫所傳回的值一律是指向 SpmiStatVals 結構的指標，其資料值會解碼並在值引數中傳回。

檔案