CREATE FUNCTION

クラス内でメソッドとして関数を生成します。

Synopsis

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

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

引数

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

概要

CREATE FUNCTION 文は、クラスのメソッドとして関数を生成します。このクラス・メソッドは、SQL ストアド・プロシージャとして投影されます。CREATE PROCEDURE 文は、SQL ストアド・プロシージャとして投影されるメソッドの生成にも使用できます。メソッドで値を返すときには CREATE FUNCTION を使用する必要がありますが、値を返さないメソッドの生成にも使用できます。

関数の生成には、GRANT コマンドで指定された %CREATE_FUNCTION 管理者特権が必要です。

SQL 文内からの 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 エラーが発行されます。

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

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

parameter-list

値を関数に渡すために使用するパラメータのリストです。パラメータのリストは括弧で囲み、リストのパラメータ宣言はコンマで区切ります。リスト内の各パラメータ宣言は、(先頭から順番に) 以下の要素で構成します。

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

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

CREATE FUNCTION 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 ストアド・プロシージャとして投影されることを指定します。ストアド・プロシージャはサブクラスに継承されます。CREATE FUNCTION は常に SQL ストアド・プロシージャに投影するため、このキーワードはオプションです。このキーワードは、PROC と略すことができます。
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 です。

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 を使用して終了し、(オプションで) 完了時に値を返す) を明示的に定義する必要があります。

ストアド・プロシージャが呼び出されると、クラス %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 として設定することによって、エラー・コンテキストを設定することができます。

指定した関数が既に存在する場合は、SQLCODE -361 エラーが生成されます。

ユーザ定義関数の実行

以下のように SELECT 文内で関数を実行できます。

SELECT StudentName,StudentAge,SQLUser.HalfAge() AS HalfTheAge
FROM SQLUser.MyStudents

この関数が存在しない場合は、SQLCODE -359 エラーが生成されます。スキーマが指定されていない場合、Caché は既定のスキーマ内でこの関数を探します。

この関数の実行結果がエラーになる場合は、SQLCODE -149 エラーが生成されます。エラーのタイプは %msg で示されます。

例

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

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

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

DROP FUNCTION RandomLetter

以下の例は、ObjectScript コードを呼び出す関数を作成します。ObjectScript コードは埋め込み SQL を含んでいます。

  &sql(CREATE FUNCTION TraineeName(
   SSN VARCHAR(11), 
   OUT Name VARCHAR(50) )
   PROCEDURE
    RETURNS VARCHAR(30)
    FOR SQLUser.MyStudents
    LANGUAGE OBJECTSCRIPT
    {
        NEW SQLCODE,%ROWCOUNT
        SET Name=""
        &sql(SELECT Name INTO :Name FROM Sample.Employee 
             WHERE SSN = :SSN)
        IF $GET(%sqlcontext)'= "" {
           SET %sqlcontext.%SQLCODE=SQLCODE
           SET %sqlcontext.%ROWCOUNT=%ROWCOUNT }
           QUIT Name
     })
    IF SQLCODE=0 { WRITE !,"Created a function" QUIT}
    ELSE { WRITE !,"CREATE FUNCTION error: ",SQLCODE," ",%msg,!
      &sql(DROP FUNCTION TraineeName FROM SQLUser.MyStudents) }
      IF SQLCODE=0 { WRITE !,"Dropped a function" QUIT}
      ELSE { WRITE !,"Drop error: ",SQLCODE }

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