CREATE METHOD

クラスにメソッドを生成します。

Synopsis

CREATE [STATIC] METHOD name (parameter_list) 
    [ characteristics ]
   [ LANGUAGE SQL ]
   BEGIN
code_body ;
   END

CREATE [STATIC] METHOD name (parameter_list) 
    [ characteristics ]
    LANGUAGE OBJECTSCRIPT
   { code_body }

引数

name	生成するメソッドの名前。識別子です。このメソッド名は、修飾されていない場合 (StoreName) または修飾されている場合 (Patient.StoreName) があります。パラメータを指定しない場合でも、name の後ろには括弧を付加する必要があります。詳細は、"Caché SQL の使用法" の “識別子“ の章を参照してください。
parameter_list	オプション — メソッドに渡すパラメータのリスト。パラメータのリストは括弧で囲み、パラメータはコンマで区切ります。パラメータを指定しない場合でも、括弧は必須です。
characteristics	オプション — メソッドの性質を指定する 1 つ以上のキーワード。使用可能なキーワードは、RETURNS、FOR、FINAL、PRIVATE、PROCEDURE、SELECTMODE です。 characteristics キーワード句の RESULT SETS、DYNAMIC RESULT SETS、または DYNAMIC RESULT SETS n を指定できます。n は整数です。これらの句は、同義語です。DYNAMIC キーワードと整数 n は、互換性を維持するために指定される空命令です。複数の特性は空白 (スペースまたは改行) で区切ります。特性は任意の順序で指定できます。
LANGUAGE OBJECTSCRIPT LANGUAGE SQL	オプション — code_body で使用するプログラミング言語。LANGUAGE OBJECTSCRIPT (ObjectScript の場合) または LANGUAGE SQL を指定します。LANGUAGE 節が省略される場合は、SQL が既定です。
code_body	メソッドのプログラム・コード。 SQL プログラム・コードの開始には BEGIN キーワードを使用し、終了には END キーワードを使用します。code_body 内の完結した各 SQL 文は、セミコロン (;) で終わります。 ObjectScript プログラム・コードは中括弧で囲みます。ObjectScript のコード行は、インデントする必要があります。

概要

CREATE METHOD 文は、クラス・メソッドを生成します。このクラス・メソッドは、ストアド・プロシージャにすることも、しないことも可能です。メソッドを SQL ストアド・プロシージャとして公開されているクラスに生成するには、PROCEDURE キーワードを指定する必要があります。既定では、CREATE METHOD はストアド・プロシージャでもあるメソッドを生成しませんが、CREATE PROCEDURE 文はそのようなメソッドを常に生成します。

オプションの STATIC キーワードは、作成されたメソッドが静的 (クラス) メソッドであり、インスタンス・メソッドでないことを明確化するために用意されています。このキーワードには、実際の機能はありません。

メソッドの生成には、GRANT コマンドで指定された %CREATE_METHOD 管理者特権が必要です。定義された所有者を持つ既存のクラスのメソッドを作成しようとする場合、クラスの所有者としてログインする必要があります。そうでない場合、操作は SQLCODE -99 エラーで失敗します。

以下の 2 つの例は、両方とも同じクラス・メソッドの作成を示しています。最初の例は CREATE METHOD を使用し、2 番目はクラス User.Letters のクラス・メソッドを定義します。

CREATE METHOD RandCaseLetter(IN caps CHAR) 
  RETURNS INTEGER 
  PROCEDURE 
LANGUAGE OBJECTSCRIPT
{
:Top
 IF caps="U" {SET x=$RANDOM(91) IF x>64 {QUIT $CHAR(x)}
   ELSE {GOTO Top}}
 ELSEIF caps="L" {SET x=$RANDOM(123) IF x>97 {QUIT $CHAR(x)}
   ELSE {GOTO Top}}
 ELSE {QUIT "case must be 'U' or 'L'"}
}

Class User.Letters Extends %Persistent [ DdlAllowed ] 
{
 ClassMethod RandCaseLetter(caps) As %String [ SqlName = RandomLetter, SqlProc ]
  { 
   Top
   IF caps="U" {SET x=$RANDOM(91) IF x>64 {QUIT $CHAR(x)}
         ELSE {GOTO Top}}
     ELSEIF caps="L" { SET x=$RANDOM(123)  IF x>97 {QUIT $CHAR(x)}
      ELSE {GOTO Top}}
      ELSE {QUIT "case must be 'U' or 'L'"}
  }
}

SQL 文内からのメソッドの呼び出しの詳細は、"Caché SQL の使用法" の “データベースの問い合わせ” の章にある "ユーザ定義関数" を参照してください。さまざまな状況での SQL ストアド・プロシージャの呼び出しについては、"CALL" 文を参照してください。

引数

name

生成するメソッドの名前。この名前は、非修飾 (StoreName) にして既定のスキーマ名を使用しても、スキーマ名を指定して修飾 (Patient.StoreName) してもかまいません。_CURRENT_USER をスキーマ名として指定した場合、Caché は既定のスキーマ名を使用します。$SYSTEM.SQL.DefaultSchema()Opens in a new tab メソッドを使用して、既定のスキーマ名を確認できます。既定のスキーマ名 SQLUser は、クラス・パッケージ名 User に対応しています。

FOR 特性 (後述) は、name で指定されたクラス名をオーバーライドすることに注意してください。この名前のメソッドが既に存在する場合、この操作は失敗して SQLCODE -361 エラーが発行されます。

このメソッド名が非修飾の場合は、生成されるクラスの名前は、既定のスキーマ名の後に、ドット、“meth”、指定の name が順に続いたものになります。したがって、非修飾名 StoreName からは、User.methStoreName のようなクラス名が得られます。詳細は、"Caché SQL の使用法" の “ストアド・プロシージャの定義と使用” の章の "SQL からクラス名への変換" を参照してください。

Caché SQL では、大文字/小文字の区別が異なるだけの重複メソッド名を指定することは許可されていません。既存メソッド名と大文字/小文字区別が異なるだけのメソッド名を指定した場合には、SQLCODE -400 エラーが生成されます。

parameter-list

値をメソッドに渡すために使用されるパラメータのリストです。パラメータのリストは括弧で囲み、リストのパラメータ宣言はコンマで区切ります。パラメータを指定しない場合でも括弧は必須です。リスト内の各パラメータ宣言は、(先頭から順番に) 以下の要素で構成します。

パラメータ・モードが IN (入力値)、OUT (出力値)、または INOUT (変更値) のいずれであるかを指定するオプションのキーワード。省略した場合、既定のパラメータ・モードは IN です。
パラメータ名。パラメータ名では、大文字と小文字が区別されます。
パラメータのデータ型。
オプション：パラメータの既定値。DEFAULT キーワードの後ろに既定値を付けて指定できます。DEFAULT キーワードはオプションです。既定値が指定されていない場合、既定値は NULL であると見なされます。

メソッドからの出力値は、論理形式から表示/ODBC 形式に自動的に変換されます。

メソッドへの入力値は、既定では、表示/ODBC 形式から論理形式には変換されません。ただし、入力の表示形式から論理形式への変換は、$SYSTEM.SQL.SetSQLFunctionArgConversion()Opens in a new tab メソッドを使用してシステム全体について構成できます。$SYSTEM.SQL.GetSQLFunctionArgConversion()Opens in a new tab を使用すると、このオプションの現在の構成を判断できます。

以下の例では、2 つの入力パラメータを指定しており、どちらにも既定値があります。オプションの DEFAULT キーワードは、1 つ目のパラメータでは指定されていますが、2 つ目のパラメータでは省略されています。

CREATE METHOD RandomLetter(IN firstlet CHAR DEFAULT 'A',IN lastlet CHAR 'Z')
BEGIN
-- SQL program code
END

characteristics

利用できるキーワードは以下のとおりです。

FOR className	メソッドを生成するクラス名を指定します。そのクラスが存在しない場合は新規作成します。メソッド名を認証することによりクラス名を指定することもできます。FOR 節で指定されたクラス名の方が、メソッド名の認証により指定されたクラス名よりも優先されます。
FINAL	サブクラスによってメソッドがオーバーライドされないように指定します。既定では、メソッドは Final ではありません。FINAL キーワードはサブクラスによって継承されます。
PRIVATE	メソッドがそれ自身のクラス、またはサブクラスの他のメソッドによってのみ起動できることを指定します。既定ではメソッドはパブリックで、制限なしに起動できます。この制限はサブクラスによって継承されます。
PROCEDURE	メソッドが SQL ストアド・プロシージャであることを指定します。ストアド・プロシージャはサブクラスに継承されます (このキーワードは、PROC と略すことができます)。
RESULT SETS DYNAMIC RESULT SETS [n]	作成されるメソッドに ReturnResultsets キーワードが含まれることを指定します。この characteristics 句のすべての形式は同義語です。
RETURNS datatype	このメソッドの呼び出しで返される値のデータ型を指定します。RETURNS が省略されると、メソッドは値を返すことができません。この指定内容はサブクラスによって継承され、サブクラスによって変更できます。この datatype には、MINVAL、MAXVAL、SCALE などのタイプのパラメータを指定できます。例えば RETURNS DECIMAL(19,4) のように指定します。値が返されるとき、datatype の長さは無視されます。例えば、RETURNS VARCHAR(32) は、このメソッドの呼び出しによって返されるあらゆる長さの文字列を受け取ることができます。
SELECTMODE mode	LANGUAGE が SQL (既定値) の場合にのみ使用されます。これを指定した場合、Caché は、#SQLCOMPILE SELECT=mode 文を対応するクラス・メソッドに追加することで、指定された SELECTMODE で、メソッドで定義された SQL 文を生成します。mode に指定できる値は、LOGICAL、ODBC、RUNTIME、および DISPLAY です。既定は LOGICAL です。

メソッドに対して有効でないクエリ・キーワード (CONTAINSID や RESULTS など) を指定する場合、システムは SQLCODE -47 エラーを発行します。重複するクエリ・キーワード (例： FINAL FINAL) を指定した場合は、SQLCODE -44 エラーが生成されます。

SELECTMODE 節は、SELECT クエリ操作、および INSERT と UPDATE 操作で使用します。これは、コンパイル時の選択モードを指定します。SELECTMODE に指定した値は、#SQLCompile Select=mode のように ObjectScript クラス・メソッド・コードの最初に追加されます。詳細は、"Caché ObjectScript の使用法" の “ObjectScript マクロとマクロ・プリプロセッサ“ の章にある "#SQLCompile Select" を参照してください。

SELECT クエリでは、SELECTMODE はデータを返すモードを指定します。mode 値が LOGICAL の場合は、論理 (内部保存) 値が返されます。例えば、日付は $HOROLOG 形式で返されます。mode 値が ODBC の場合、論理と ODBC 間の変換が適用され、ODBC 形式値が返されます。mode 値が DISPLAY の場合、論理と表示間の変換が適用され、表示形式値が返されます。mode 値が RUNTIME の場合、実行時に表示モードを (LOGICAL、ODBC、または DISPLAY に) 設定できます。
INSERT または UPDATE 操作では、SELECTMODE RUNTIME オプションで、表示形式 (DISPLAY または ODBC) から論理格納形式への入力データ値の自動変換がサポートされています。このコンパイルされた表示データから論理データへの変換コードは、SQL コード実行時の選択モード設定が LOGICAL (すべての Caché SQL 実行インタフェースの既定値) の場合のみ適用されます。

"Caché SQL の使用法" の “ダイナミック SQL の使用法” の章に説明されているように、SQL コードが実行されると、%SQL.StatementOpens in a new tab クラスの %SelectModeOpens in a new tab プロパティが、実行時の選択モードを指定します。SelectMode オプションの詳細は、"Caché SQL の使用法" の “Caché SQL の基礎” の章にある “データ表示オプション” を参照してください。

LANGUAGE

code_body に使用している言語を指定するキーワード節。使用可能な節は、LANGUAGE OBJECTSCRIPT (ObjectScript の場合) か、LANGUAGE SQL です。LANGUAGE 節が省略される場合は、SQL が既定です。

code_body

生成されるメソッドのプログラム・コード。このコードは SQL または ObjectScript で指定します。使用する言語は LANGUAGE 節と一致させる必要があります。ただし、ObjectScript のコードには埋め込み SQL を記述できます。

Caché は、メソッドの実際のコードを生成するために提供されたコードを使用します。

指定するコードが SQL の場合、メソッドの生成時に Caché によってコード行が追加されます。追加のコードでは、SQL が ObjectScript "ラッパ" に埋め込まれ、(必要に応じて) プロシージャ・コンテキスト・ハンドラが作成され、返り値が処理されます。以下はこの Caché から生成されたラッパ・コードの例です。

   NEW SQLCODE,%ROWID,%ROWCOUNT,title
   &sql( SELECT col FROM tbl )
   QUIT $GET(title)

指定するコードが OBJECTSCRIPT である場合、ObjectScript コードは中括弧で囲む必要があります。すべてのコード行を列 1 からインデントする必要がありますが、ラベルとマクロ・プリプロセッサ指示文はその必要はありません。ラベルやマクロ指示文の前には、列 1 でコロン (:) を付加する必要があります。

ObjectScript コードの場合、"ラッパ" (変数を NEW で処理して、QUIT を使用して終了し、(オプションで) 完了時に値を返す) を明示的に定義する必要があります。

PROCEDURE キーワードを指定することで、メソッドをストアド・プロシージャとして公開することができます。ストアド・プロシージャが呼び出されると、クラス %Library.SQLProcContextOpens in a new tab のオブジェクトが %sqlcontext 変数でインスタンス化されます。このプロシージャ・コンテキスト・ハンドラによって、プロシージャとその呼び出し元 (ODBC サーバなど) 間でプロシージャ・コンテキストの受け渡しが行われます。

%sqlcontext は、エラー・オブジェクト、SQLCODE エラー・ステータス、SQL 行カウント、およびエラー・メッセージを含む、いくつかのプロパティで構成されます。以下の例は、これらプロパティの設定に使用される値を示しています。

  SET %sqlcontext.%SQLCODE=SQLCODE
  SET %sqlcontext.%ROWCOUNT=%ROWCOUNT
  SET %sqlcontext.%Message=%msg

SQLCODE と %ROWCOUNT の値は、SQL 文の実行によって自動的に設定されます。%sqlcontext オブジェクトは、実行される前に毎回リセットされます。

または、%SYSTEM.Error オブジェクトをインスタンス化し、%sqlcontext.Error として設定することによって、エラー・コンテキストを設定することができます。

例

以下の例は、SQL コードで CREATE METHOD を使用して、Sample.Employee クラスに UpdateSalary メソッドを生成しています。

CREATE METHOD UpdateSalary ( IN SSN VARCHAR(11), IN Salary INTEGER )
   FOR Sample.Employee
   BEGIN
     UPDATE Sample.Employee SET Salary = :Salary WHERE SSN = :SSN;
   END

以下の例では、ランダムな大文字を生成するプロシージャとして格納される RandomLetter() メソッドを作成します。その後、このメソッドを関数として SELECT 文内で呼び出すことができます。RandomLetter() メソッドを削除するため、DROP METHOD が指定されています。

CREATE METHOD RandomLetter()
RETURNS INTEGER
PROCEDURE
LANGUAGE OBJECTSCRIPT
{
:Top
 SET x=$RANDOM(91)
 IF x<65 {GOTO Top}
 ELSE {QUIT $CHAR(x)}
}

SELECT Name FROM Sample.Person
WHERE Name %STARTSWITH RandomLetter()

DROP METHOD RandomLetter

以下の埋め込み SQL の例は、ObjectScript コードで CREATE METHOD を使用して、SQLUser.MyStudents クラスに TraineeTitle メソッドを生成し、Title 値を返します。

  &sql(CREATE METHOD TraineeTitle(
   IN SSN VARCHAR(11), 
   INOUT Title VARCHAR(50) )
    RETURNS VARCHAR(30)
    FOR SQLUser.MyStudents
    LANGUAGE OBJECTSCRIPT
    {
        NEW SQLCODE,%ROWCOUNT
        &sql(SELECT Title INTO :Title FROM Sample.Employee 
             WHERE SSN = :SSN)
        IF $GET(%sqlcontext)'= "" {
           SET %sqlcontext.%SQLCODE=SQLCODE
           SET %sqlcontext.%ROWCOUNT=%ROWCOUNT }
           QUIT
     })
    IF SQLCODE=0 { WRITE !,"Created a method" QUIT}
    ELSEIF SQLCODE=-361 { WRITE !,"Method already exists SQLCODE: ",SQLCODE
      &sql(DROP METHOD TraineeTitle FROM SQLUser.MyStudents)
      IF SQLCODE=0 { WRITE !,"Dropped a method" QUIT}}
    ELSE { WRITE !,"SQL error: ",SQLCODE }

%sqlcontext オブジェクトを使用します。対応する SQL 変数を使用して、その %SQLCODE プロパティおよび %ROWCOUNT プロパティを設定します。メソッドの LANGUAGE OBJECTSCRIPT キーワードに続く ObjectScript コードを中括弧で囲むことに注意してください。ObjectScript コードには、&sql でマークされ、角括弧で囲まれた埋め込み SQL コードがあります。