17.00 - 17.05 - C/C++関数本体 - Advanced SQL Engine - Teradata Database

Teradata Vantage™ - SQL外部ルーチン プログラミング

Product
Advanced SQL Engine
Teradata Database
Release Number
17.00
17.05
Published
2020年6月
Content Type
プログラミング リファレンス
Publication ID
B035-1147-170K-JPN
Language
日本語 (日本)

C/C++関数の基本的な定義方法

UDMとしてC/C++関数を定義するための基本的な手順は、次のとおりです。

  1. SQL_TEXT定数を定義します。

    詳細については、ヘッダー ファイルのSQL_TEXTの定義を参照してください。

  2. sqltypes_td.hヘッダー ファイルをインクルードします。

    詳細については、ヘッダー ファイルを参照してください。

  3. その関数で使用するマクロや変数が定義されているその他のヘッダー ファイルをインクルードします。
  4. CREATE TYPE文のMETHOD指定で指定されたパラメータ受渡し規則に定められた順序でのパラメータ リストを定義します。

    詳細については、UDMのパラメータ リストを参照してください。

  5. 関数を実装し、該当する値を結果として設定します。

    関数が、STRUCTURED型UDT用のコンストラクタUDMであるか、または変換、整列、またはキャストの機能を提供するインスタンスUDMである場合、実装において特定の要件を満たす必要があります。

    実装するC/C++関数の詳細 参照先
    コンストラクタUDMである場合 コンストラクタUDM
    UDT用のキャスト機能を提供する場合 UDT用のキャスト機能を提供するUDM
    UDT用の整列機能を提供する場合 UDT用の整列機能を提供するUDM
    UDT用の変換機能を提供する場合 UDT用の変換機能を提供するUDM
  6. 関数でエラーが発生した場合、以下を設定します。
    • 関数を終了する前に、sqlstate引数をSQLSTATE例外または警告条件に設定します。

      詳細については、SQLSTATEの値を戻すを参照してください。

    • error_message文字列をエラー メッセージ テキストに設定します。その文字はLATIN文字範囲内のものでなければなりません。入力時にこの文字列は、NULL終了文字列に初期設定しておきます。
  7. メソッドでパラメータ スタイルSQLを使用する場合は、indicator_result引数を設定します。
    呼び出し側 indicator_result引数の設定値
    NULL -1
    非NULL 0

例: 基本的なUDM

DISTINCT型UDT用のインスタンスUDMを実装する簡単なC関数の例を以下に示します。この関数は、メートル単位のUDTの値を使用し、それに相当するインチ単位の値を戻します。このUDMでは、パラメータ スタイルTD_GENERALを使用しています。

/*****  C source file name: to_inches.c  *****/

#define  SQL_TEXT Latin_Text
#include <sqltypes_td.h>
#include <string.h>

void meter_toInches( UDT_HANDLE  *meterUdt,
                     FLOAT       *result,
                     char         sqlstate[6])
{
   FLOAT value;
   int length;

   /* Get meter's value. */
   FNC_GetDistinctValue(*meterUdt, &value, SIZEOF_FLOAT, &length);

   /* Convert meters to inches and set the result value. */
   *result = value * 3.28 * 12;
}

UDMでのUDTハンドルの使用

Teradata Databaseには、UDMで値を戻すためにUDT_HANDLE入力引数と共に使用するライブラリ関数が用意されています。

目的 使用するライブラリ関数
DISTINCT型の値を取得する FNC_GetDistinctValue
DISTINCT型の値を設定する FNC_SetDistinctValue
LOBを表わすDISTINCT型のロケータを取得する FNC_GetDistinctInputLob
FNC_GetDistinctResultLob
STRUCTURED型の属性値を取得する FNC_GetStructuredAttribute
STRUCTURED型の属性値を設定する FNC_SetStructuredAttribute
STRUCTURED型LOB属性のロケータを取得する FNC_GetStructuredInputLobAttribute
FNC_GetStructuredResultLobAttribute

ライブラリ関数の使用方法の詳細は、このドキュメントの別の箇所に記載されています。

操作 参照先
DISTINCT型UDTの値にアクセスする方法 DISTINCT型UDTの値へのアクセス
STRUCTURED型UDTの属性値にアクセスする方法 STRUCTURED型UDTの属性値へのアクセス
DISTINCT型UDTの結果の値を設定する方法 DISTINCT型UDTの結果の値の設定
STRUCTURED型UDTの結果の属性値を設定する方法 STRUCTURED型UDTの結果の属性値の設定

UDT用のキャスト機能を提供するUDM

関数がUDT用のキャスト機能を提供するインスタンスUDMの場合、そのC/C++関数は以下の要件を満たす必要があります。

メソッドが実装するキャスト機能 C/C++関数が設定する必要のある内容
変換元 変換先
別のUDTまたは事前定義型 STRUCTURED型UDT 入力引数の値を使って、UDTの結果の属性値を設定する。
DISTINCT型UDT 入力引数の値を使って、UDTの結果の値を設定する。
STRUCTURED型UDT 別のUDTまたは事前定義型 UDT入力引数の属性値を使って、結果の値を設定する。
DISTINCT型UDT UDT入力引数の値を使って、結果の値を設定する。

DISTINCT型とその事前定義ソース型の間のキャスト機能は、Teradata Databaseによって自動的に生成されます。DISTINCT型とその他の事前定義のデータ型またはUDTの間のキャストのために、付加的なメソッドを作成することもできます。

キャスト機能を提供するUDMの実装方法の例は、UDMのサンプル コードを参照してください。

UDT用の整列機能を提供するUDM

関数が2つのUDTを比較する整列機能を提供するインスタンスUDMである場合、実装では以下の要件を満たす必要があります。

呼び出し側 C/C++関数が設定する必要のある内容
STRUCTURED Teradata Databaseで比較のために使用される値に対して結果を設定するためのUDTの属性値。
DISTINCT Teradata Databaseで比較のために使用される値に対して結果を設定するためのUDTの値。

ソース データ型がLOBでない場合には、DISTINCT型の作成時に、Teradata Databaseは整列機能を自動生成しません。ただし、この機能を除去して独自の機能を用意することもできます。

整列機能を提供するUDMを実装する方法の例は、UDMのサンプル コードを参照してください。

UDT用の変換機能を提供するUDM

関数がサーバーからUDTをエクスポートする変換機能を提供するインスタンスUDMである場合、実装では以下の要件を満たす必要があります。

呼び出し側 C/C++関数が変換する必要のある内容
STRUCTURED UDTの属性値を、事前定義型の結果に適した値に変換する。
DISTINCT UDTの値を、事前定義型の結果に適した値に変換する。

変換機能は、DISTINCT型の作成時にTeradata Databaseによって自動的に生成されますが、この機能を除去して独自の機能を用意することもできます。

変換機能を提供するUDMを実装する方法の例は、UDMのサンプル コードを参照してください。

コンストラクタUDM

関数がSTRUCTURED型UDT用のコンストラクタUDMである場合、C/C++関数では以下のことを実行する必要があります。
  • 結果UDTの属性値を、UDMの呼び出し対象であるUDTの属性値に設定する。
  • 結果UDTの属性値を、それに対応する入力引数の値に設定する。

コンストラクタ メソッドを実装する方法の例は、UDMのサンプル コードを参照してください。

CLOB引数またはBLOB引数を使用するUDM

UDMでは、CLOBまたはBLOBの入出力引数を定義し、ロケータによって渡すことができます。

CLOB引数またはBLOB引数を使用するUDMの実装に関するガイドラインは、CLOB引数またはBLOB引数を使用するUDFの実装に対するガイドラインによく似ています。詳細は、LOB型を使用する関数の定義を参照してください。

PERIOD引数を使用するUDM

UDMでは、PERIODの入力引数および出力引数を定義して、それらをPDTハンドルで受け渡すことができます。

PERIOD引数を使用するUDMを定義するためのガイドラインは、PERIOD引数を使用するスカラーUDFを定義するためのガイドラインとよく似ています。詳細は、PERIOD型を使用する関数の定義を参照してください。

ARRAY引数を使用するUDM

UDMでは、ARRAY入力引数および出力引数を定義して、それらをARRAYハンドルで受け渡すことができます。

ARRAY引数を使用するUDMを定義するためのガイドラインは、ARRAY引数を使用するスカラーUDFを定義するためのガイドラインとよく似ています。詳細は、ARRAY型を使用する関数の定義を参照してください。

TD_ANYTYPE引数を使用するUDM

TD_ANYTYPEデータ型の入力パラメータおよび出力パラメータを使用してUDMを定義できます。

TD_ANYTYPE引数を使用するUDMを定義するためのガイドラインは、TD_ANYTYPE引数を使用するスカラーUDFを定義するためのガイドラインとよく似ています。詳細は、TD_ANYTYPE型を使用する関数の定義を参照してください。