%Status 値の操作
%StatusOpens in a new tab 値 (status) を返す API を扱う場合、続行する前にステータスを確認し、成功の場合にのみ通常の処理を続行するのがベスト・プラクティスです。独自のコードでは、ステータス値を返す (および必要に応じて別の場所でその値を確認する) こともできます。
このページでは、ステータス値とその操作方法について説明します。
ステータス値の操作の基本
InterSystems IRIS® データ・プラットフォームのクラスの多くに含まれるメソッドでは、%StatusOpens in a new tab (%Library.StatusOpens in a new tab) 値を返すことで、成功またはエラーを示します。ステータスがエラーを表す場合、エラーに関する情報もステータスに含まれます。例えば、%Library.PersistentOpens in a new tab の %Save() メソッドはステータスを返します。このようなメソッドでは、返されるステータスを必ず取得してください。その後、ステータスを確認して適切に処理を続行します。これには、以下の 2 つのシナリオが考えられます。
-
成功の場合、ステータスは 1 になります。
-
失敗の場合、ステータスは、エラー・ステータスおよび 1 つ以上のエラー・コードとテキスト・メッセージを含むエンコードされた文字列です。ステータス・テキスト・メッセージはユーザのロケールの言語でローカライズされています。InterSystems IRIS では、値を処理するためのメソッドとマクロが用意されているため、失敗の性質を理解することができます。
基本的なツールは以下のとおりです。
-
ステータスが成功またはエラーのどちらを表すかを確認するには、以下のいずれかを使用します。
-
$$$ISOK マクロと $$$ISERR マクロ。これらはインクルード・ファイル %occStatus.inc で定義されています。このインクルード・ファイルは、すべてのオブジェクト・クラスで自動的に利用可能です。
-
$SYSTEM.Status.IsOK() および $SYSTEM.Status.IsError() メソッド。
-
-
エラーの詳細を表示するには、$SYSTEM.Status.DisplayError() または $SYSTEM.OBJ.DisplayError() を使用します。これらのメソッドは、互いに同等です。出力は現在のデバイスに書き込まれます。
-
エラーの詳細を含む文字列を取得するには、$SYSTEM.Status.GetErrorText() を使用します。
$SYSTEM 特殊変数は %SYSTEM パッケージに結合されます。これは、以前のリストのメソッドが %SYSTEM.StatusOpens in a new tab および %SYSTEM.OBJOpens in a new tab クラスにあることを意味します。詳細は、クラス・リファレンスを参照してください。
例
以下に例を示します。
Set object=##class(Sample.Person).%New()
Set object.Name="Smith,Janie"
Set tSC=object.%Save()
If $$$ISERR(tSC) {
Do $SYSTEM.Status.DisplayError(tSC)
Quit
}
以下に、$SYSTEM.Status.GetErrorText() の使用法を示す部分的な例を示します。
If $$$ISERR(tSC) {
// if error, log error message so users can see them
Do ..LogMsg($System.Status.GetErrorText(tSC))
}
一部の ObjectScript プログラマは、文字 t を接頭語として使用して一時変数であることを示すため、コード・サンプルで "一時ステータス・コード" を意味する tSC が変数名として使用されることがあります。この規則を使用するのは自由ですが、この変数名に特別なことは何もありません。
バリエーション (%objlasterror)
%New() のような一部のメソッドは、%StatusOpens in a new tab を返しませんが、ステータスを含む %objlasterror 変数を更新します。%New() は、成功時にはクラスのインスタンスに OREF を返し、失敗時には NULL 文字列を返します。以下の例で示すように、%objlasterror 変数にアクセスして、この種のメソッドのステータス値を取得することができます。
Set session = ##class(%CSP.Session).%New()
If session="" {
Write "session oref not created",!
Write "%New error is ",!,$System.Status.GetErrorText(%objlasterror),!
} Else {
Write "session oref is ",session,!
}
詳細は、%SYSTEM.StatusOpens in a new tab のクラスを参照してください。
1 つのステータス値で報告される複数のエラー
1 つのステータス値が複数のエラーを表す場合、前述の手法で得られるのは最後のエラーの情報のみです。%SYSTEM.StatusOpens in a new tab は、個々のエラーを取得するのに使用できるメソッド、GetOneErrorText()Opens in a new tab および GetOneStatusText()Opens in a new tab を提供します。以下に例を示します。
CreateCustomErrors
SET st1 = $System.Status.Error(83,"my unique error")
SET st2 = $System.Status.Error(5001,"my unique error")
SET allstatus = $System.Status.AppendStatus(st1,st2)
DisplayErrors
WRITE "All together:",!
WRITE $System.Status.GetErrorText(allstatus),!!
WRITE "One by one",!
WRITE "First error format:",!
WRITE $System.Status.GetOneStatusText(allstatus,1),!
WRITE "Second error format:",!
WRITE $System.Status.GetOneStatusText(allstatus,2),!
もう 1 つのオプションは $SYSTEM.Status.DecomposeStatus() です。このメソッドは、エラーの詳細の配列を (参照によって、2 つ目の引数として) 返します。以下に例を示します。
Do $SYSTEM.Status.DecomposeStatus(tSC,.errorlist)
//then examine the errorlist variable
変数 errorlist は、エラー情報が含まれる多次元配列です。以下に、部分的な例を示します (読みやすいように人為的に改行が追加されています)。
ZWRITE errorlist
errorlist=2
errorlist(1)="ERROR #5659: Property 'Sample.Person::SSN(1@Sample.Person,ID=)' required"
errorlist(1,"caller")="%ValidateObject+9^Sample.Person.1"
errorlist(1,"code")=5659
errorlist(1,"dcode")=5659
errorlist(1,"domain")="%ObjectErrors"
errorlist(1,"namespace")="SAMPLES"
errorlist(1,"param")=1
errorlist(1,"param",1)="Sample.Person::SSN(1@Sample.Person,ID=)"
...
errorlist(2)="ERROR #7209: Datatype value '' does not match
PATTERN '3N1""-""2N1""-""4N'"_$c(13,10)_" >
ERROR #5802: Datatype validation failed on property 'Sample.Person:SSN',
with value equal to """""
errorlist(2,"caller")="zSSNIsValid+1^Sample.Person.1"
errorlist(2,"code")=7209
...
各エラー・メッセージをログに記録したい場合は、前述のロギングの例を以下のように変更できます。
If $$$ISERR(tSC) {
// if error, log error message so users can see them
Do $SYSTEM.Status.DecomposeStatus(tSC,.errorlist)
For i=1:1:errorlist {
Do ..LogMsg(errorlist(i))
}
}
DecomposeStatus() を再び呼び出して同じエラー配列を渡すと、新しいエラーが配列に付加されます。
%Status を返す
ユーザがユーザ独自のカスタム・ステータス値を返すことができます。%StatusOpens in a new tab を作成するには、以下の構文を使用します。
$$$ERROR($$$GeneralError,"your error text here","parm","anotherparm")
または、以下も同じ意味です。
$SYSTEM.Status.Error($$$GeneralError,"your error text here", "parm","anotherparm")
ここで、"parm" および "anotherparm" は、処理が成功しなかったレコードのファイル名や識別子など、オプションの追加のエラー引数を表します。
以下に例を示します。
quit $$$ERROR($$$GeneralError,"Not enough information for request")
他のエラーに関する情報を含めるには、$SYSTEM.Status.AppendStatus() を使用してステータス値を変更します。以下に例を示します。
set tSC=$SYSTEM.Status.AppendStatus(tSCfirst,tSCsecond)
quit tSC
%SYSTEM.Error
%SYSTEM.ErrorOpens in a new tab クラスは一般的なエラー・オブジェクトです。これは %StatusOpens in a new tab エラー、例外オブジェクト、$ZERROR エラー、または SQLCODE エラーから作成することができます。
%SYSTEM.ErrorOpens in a new tab クラス・メソッドを使用すれば、%StatusOpens in a new tab を例外に、または例外を %StatusOpens in a new tab に変換することができます。
関連項目
詳細は、"%SYSTEM.StatusOpens in a new tab" クラスおよび "%StatusOpens in a new tab (%Library.StatusOpens in a new tab)" クラスのクラス・リファレンスを参照してください。