17.00 - 17.05 - DBCExtension.GLOP_Addストアド プロシージャ - 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
日本語 (日本)

目的

GLOPデータおよびGLOPマッピングをGLOPセットに追加するには、GLOP_Addを使用します。

定義

CREATE PROCEDURE DBCExtension.GLOP_Add
   (IN Set_name     VARCHAR(257) CHARACTER SET UNICODE,
    IN Type_g       CHAR(2) CHARACTER SET LATIN,
    IN Association  VARCHAR(257) CHARACTER SET UNICODE,
    IN Data_Name    VARCHAR(128) CHARACTER SET UNICODE,
    IN Shared       CHAR(1) CHARACTERS SET LATIN,
    IN Map_Index    BYTEINT,
    IN Map_Page     VARCHAR(1) CHARACTER SET LATIN,
    IN Mode_g       CHAR(1) CHARACTER SET LATIN,
    IN Disable      CHAR(1) CHARACTER SET LATIN,
    IN Ageing       INTEGER,
    IN Length       INTEGER,
    IN Page         INTEGER,
    IN Data         BLOB(2097088000)
   )

説明

Set_name
GLOPセットの名前またはテーブルの名前(Type_g引数の値によって決まります)。
Type_gが次の場合:
  • 非NULLの場合は、Set_nameは、関連するデータベースを含むセットの名前です。名前が完全修飾されていない場合、現行のデフォルト データベースが想定されます。セット名は固有のTVM名でなければなりません。セット名がユーザーのアクセス先のGLOPセットに関連付けられていない場合、システムによりエラーが報告されます。
  • NULLの場合は、Set_name は、作成するGLOPセットの複数の行に同等のデータが含まれているテーブルの名前です。テーブルが現行のデフォルト データベースに置かれていない場合、名前は完全修飾されていなければなりません。

    その他のすべての引数は無視されるので、NULLに設定できます。

    テーブルに指定されていなければならない定義について詳しくは、使用上の注意を参照してください。

Type_g
GLOPの型。有効な値は以下のとおりです。
  • 'SY': システムGLOPを指します。
  • 'RO': ロールGLOPを指します。
  • 'US': ユーザーGLOPを指します。
  • 'SE': セッションGLOPを指します。
  • 'TR': トランザクションGLOPを指します。
  • 'RE': リクエストGLOPを指します。
  • 'XR': 外部ルーチンGLOPを指します。
  • NULLは、Set_name引数が、データを入れるテーブルの名前を提供することを意味します。

GLOP型の意味の詳細については、GLOP型を参照してください。

Association
特定のGLOP型の関係。
Type_gが次の場合:
  • 'RO': 関連性はロールの名前です。
  • 'US': 関連性はユーザー名です。
  • 'XR': 関連性は外部ルーチン名です。

    外部ルーチンが現行のデフォルト データベースに置かれていない場合、名前は完全修飾されていなければなりません。UDFの場合、外部ルーチン名はルーチンの固有の名前でなければなりません。

  • その他の値の場合には、関連性はすべて無視し、NULLに設定します。

関係名がGLOPデータについてすでに存在する場合、または名前がデータベースにない場合、システムによりエラーが報告されます。

Data_Name
所定のデータベースについてGLOPデータに割り当てられる名前。そのデータ名が所定のデータベースに対して存在し、Data引数がNULLに設定されていない場合、エラーが報告されます。
Shared
GLOPマッピング属性。有効な値は以下のとおりです。
  • 'Y'は、GLOPマッピングが共有されることを意味します。

    GLOPマッピングは、同一セット内または同一データベースで定義された別のセット内のGLOP型の間で共有できます。

  • 'N'は、GLOPマッピングが共有されないことを意味します。

GLOPマッピング属性の詳細については、GLOPデータ属性を参照してください。

Map_Index
GLOPアドレスが外部ルーチンで検出されるマップ配列内の位置。有効な値は0から7です。
Map_Page
[読み取り専用GLOPデータの場合]このページをMap_Index引数で指定されたインデックスについてマップする最初のページにするかどうか。有効な戻り値は以下のとおりです。
  • 'Y': このページをMap_Index引数で指定されたインデックスについてマップする最初のページにするよう指定します。
  • 'N'またはNULL: このページを指定されたインデックスについてマップする最初のページにしないよう指定します。

このインデックスでマップされるページがすでにある場合、システムによりエラーが戻されます。

Mode_g
GLOP変更属性。有効な戻り値は以下のとおりです。
  • 'R': 読み取り専用GLOPであることを指定します。

    デフォルトでは、読み取り専用GLOPは常に通常です。

  • 'W': 読み取り/書き込みGLOPであることを指定します。
  • 'M': グローバルに変更可能な読み取り/書き込みGLOPであることを指定します。

GLOP変更属性の詳細については、GLOPデータ属性を参照してください。

Disable
以下のいずれかの値です。
  • 'D': データを無効にするよう指定します。

    GLOPページはしばらく経つまで使用できません。

  • 'E': GLOPを有効にするよう指定します。
Ageing
[読み取り専用GLOPデータの場合]このページがメモリ不足でエージングするまでに待機する分数。有効な値は次のとおりです。
  • > 0: 指定された時間(分)が経過すると、このページをメモリ不足でエージングし、ページはマップされないよう指定します。
  • 0: このページをメモリ不足でエージングしないよう指定します。
  • -1: 最初にページに設定されたエージング値を使用するよう指定します。

    このページが最初のページの場合、エージング値は0に設定されます。

Length
ここで作成されるGLOPのマップ後の長さ。Data_Nameによって指定されたGLOPがすでに存在する場合、この引数は関係ありません。説明の残りの部分では、GLOPデータが初めて作成されていることを想定しています。長さフィールドは、提供されたデータの実際の長さと無関係であっても構いません。データが長い場合、マップ時に切り捨てられます。データが短い場合、マップ時に残りの長さがゼロにリセットされます。NULLを使用すると、新規のGLOPデータについてエラーが戻されます。読み取り専用GLOPデータの場合、すべてのページが同じ長さになります。

読み取り専用GLOPデータの場合に値-1を指定すると、長さが最大GLOPページの長さに設定されます。読み取り/書き込みGLOPデータまたはグローバルに変更可能なGLOPデータの場合に-1を指定すると、長さはデータの長さに設定されます。その場合にデータを指定する必要があります。

Page
[読み取り専用GLOPデータの場合]作成されるGLOPページの数。GLOPページの番号は連続していなければなりません。最初のページの値は1です。

GLOPモードが読み取り専用でない場合、このパラメータは無視されます。ページ番号の順序にすき間があったり、ページがすでに存在する場合には、システムによりエラーが報告されます。

Data
システム テーブルにロードされる実際のデータ。GLOP Data_Nameが初めてGLOPセットに追加されるときにのみデータが提供されます。それ以降、Data_Nameフィールドを経由してこのデータを別のセットまたは同じセットで使用するすべての参照では、フィールドはNULLに設定されます。データは直接指定することもできますし、この引数にBLOBを戻すUDFを指定して生成することもできます。データはNULLにすることが可能です。その場合、Lengthパラメータで指定されるGLOPはゼロにリセットされてマッピングされます。読み取り専用GLOPデータでNULLを渡すと、エラーになります。

許可

多数のユーザーのためにGLOPデータを追加する管理者は、以下の条件を満たす必要があります。
  • (DBCExtensionデータベース内の) GLOP_Set、GLOP_Map、およびGLOP_Dataテーブルに対するINSERT権限を持っている。
  • Set_Name引数にセットが追加されるデータベースが含まれている。
  • GLOP_Addを呼び出す前に作成される新規のセットごとにCREATE GLOP SET文を実行する。
(DBCExtensionデータベース内の) GLOP_Set、GLOP_Map、およびGLOP_Dataテーブルに対するINSERT権限を持っていないときに、付与された定義済みのGLOPセットのいずれかに追加するには、以下の条件を満たす必要があります。
  • GLOPの追加先のデータベースに対するGLOPまたはCREATE GLOP権限を持っている。
  • GLOPセットの作成者または所有者であり、GLOP MEMBER権限を持っている。

'RO'、'US'、または'XR' GLOPを追加するには、現行許可がそれぞれそのロール、ユーザー、または外部ルーチンに対して1つの権限を所有しているか、持っている必要があります。

Set_name引数が、GLOPセット情報を含むテーブルの名前を指定する場合、プロシージャの呼び出し側は指定されたテーブルに対するSELECT権限を持っていなければなりません。

GLOP権限について詳しくは、<Teradata Vantage™ - SQLデータ制御言語、B035-1149>を参照してください。

使用上の注意

このプロシージャは、新規のGLOPデータとその属性およびマッピングをGLOPに対して定義するために使用します。セット内の既存のデータを削除したり、置換したりする目的では使用できません。GLOPデータを削除するにはGLOP_Removeを、データが変更される場合にはGLOP_Changeを呼び出します。このプロシージャでは、作成中のデータベースにGLOPセットがすでに存在していると予想しています。そのため、特定のGLOPセット名について初めてこのプロシージャを呼び出す前に、作成する新規のGLOPセットの名前を使用してCREATE GLOP SET文を発行してください。

同じGLOPデータへの参照はすべて同じデータベースに関連付ける必要があります。複数のセットで同じGLOPデータを参照するには、初めてGLOPを追加するときにData_NameおよびDataを指定します。それ以降、同じデータを参照して追加するには、すべてData_Nameを提供し、Data引数をNULLにする必要があります。初めてGLOPデータが追加されるときが、そのデータの内容がどのようなものになるかを決定します。GLOPにデータがない場合、最初のGLOPの追加でData引数をNULLに設定すると、このことを実現できます。

すべてのパラメータで、データと整合性の有効な組み合わせが検査されます。ある場合に、提供された情報が無視されることがあります。例えば、読み取り/書き込みGLOPデータの場合、ageing値は無視されます。なぜならこの値には意味がないからです(しかし値を指定しても悪影響はありません)。パラメータ セクションで具体的に呼び出されていないいずれかのパラメータ設定に不整合がある場合、システムによりエラーが報告されます。

このプロシージャはトランザクション内から呼び出さないでください。なぜなら、このプロシージャはそれ自体のトランザクションを場合によっては複数個作成し、さらにDDL文を実行するかもしれないからです。このプロシージャはTeradataモード セッションから実行するよう設計されています。

Type_gフィールドがNULLの場合、Set_name引数にはGLOPセットに追加されるデータを入れるテーブルの名前が含まれることが期待されます。テーブルには以下の定義がなければなりません。テーブルは一時テーブルでも構いません。

CREATE TABLE GLOP_Add_Table     /* the name can be anything */
   (Sequence     INTEGER NOT NULL,
    Set_name     VARCHAR(257) CHARACTER SET UNICODE,
    Type_g       CHAR(2) CHARACTER SET LATIN,
    Association  VARCHAR(257) CHARACTER SET UNICODE,
    Data_Name    VARCHAR(128) CHARACTER SET UNICODE,
    Shared       CHAR(1) CHARACTERS SET LATIN,
    Map_Index    BYTEINT,
    Map_Page     VARCHAR(1) CHARACTER SET LATIN,
    Mode_g       CHAR(1) CHARACTER SET LATIN,
    Disable      CHAR(1) CHARACTER SET LATIN,
    Ageing       INTEGER,
    Length       INTEGER,
    Page         INTEGER NOT NULL,
    Data         BLOB(2097088000))
PRIMARY INDEX (Sequence);

定義済みの列の説明は、ストアド プロシージャのバージョンと同一で、同じ名前を持ちます。 追加された列はSequence列のみで、ここにはデータが適用される順に増えていく番号が含まれていなければなりません。データはSequence上で昇順にソートされます。 順序番号が増えなかったり、ページ番号にすき間があったりする場合、エラーが報告されます。複数ページの読み取り専用GLOPデータの場合は昇順でなければならないからです。 この技法を使用して複数のセットを追加できます。

例: DBCExtension.GLOP_Addストアド プロシージャ

PDF文書用のパーシング ルールを含むXML文書を作成します。これは初回の作成です。

CREATE GLOP SET Web_XML_Document_Markup;

CALL DBCExtension.GLOP_Add(
   'Web_XML_Document_Markup',  -- the set name
   'SE',                       -- this is session GLOP data
   NULL,                       -- Not relevant for session GLOP data
   'PDF_Mode',                 -- named the GLOP data
   NULL,                       -- shared flag not relevant
   0,                          -- Put in map index 0
   'Y',                        -- Make this the initial map page
   'R',                        -- Read-only
   'E',                        -- Not disabled
   10,                         -- Ageing is 10
   -1,                         -- Set GLOP length to data length
   1,                          -- Creating page one
   Gen_XML_PDF_Markup(...));   -- a UDF creates the GLOP data

これは読み取り専用GLOPデータなので、そのセッション型をGLOPにする必要はありませんが、そのように設定すればセッション境界で置き換えるのが簡単になるので、将来の従属性の変更に役立つかもしれません。