16.20 - TEST - Teradata Vantage NewSQL Engine

Teradata Vantage™ SQL ストアド プロシージャおよび埋め込みSQL

prodname
Teradata Database
Teradata Vantage NewSQL Engine
vrm_release
16.20
category
プログラミング リファレンス
featnum
B035-1148-162K-JPN

目的

async_statement_identifierによって識別される非同期SQL文の完了状態をテストします。

WAIT文とともに使用すると、async_statement_identifierまたはhost_variable_nameによって識別される非同期SQL文の完了状態を返しますが、リクエストが未完了の場合に待機しません。

呼び出し

実行可能形式。

埋め込みSQLのみ。

構文



async_statement_identifier
ASYNC修飾子によって割り当てられた、非同期で実行されるSQL文の、大文字小文字を区別するアプリケーション提供の識別子。
それぞれの非同期文識別子は、長さを最大で30文字にすることができ、すべてのアクティブな接続で固有にする必要があります。
:async_statement_identifier_variable_name
非同期文識別子を備えたホスト変数の名前。
この識別子は、最大で30文字の長さの固定長または可変長文字列にする必要があります。
最初のコロンは必須。

ANSI準拠

TESTは、ANSI/ISO SQL:2011規格に対するTeradataの拡張機能です。

許可

なし。

ルール

個々のasync_statement_identifier assignmentには大文字と小文字の区別があり、すべてのアクティブな接続の間で固有になっている必要がある。

個々のasync_statement_identifierの最大長は30バイトである。

:async_statement_identifier_variable_nameの変数は固定長または可変長の文字変数で、30バイトを超えてはならない。

未処理の非同期SQL文が存在しなければ、例外条件“no outstanding asynchronous SQL statement”が発生します。
  • SQLCODEは -650に設定される。
  • SQLSTATEは’04000’に設定される。
指定された非同期SQL文が未完了の場合、例外条件“SQL statement not yet complete”が発生します。
  • SQLCODEは -651に設定される。
  • SQLSTATEは’03000’に設定される。
指定された非同期SQL文が完了している場合、以下の操作が行なわれる。
  1. ランタイムはリクエストの処理を終え、SQLCODEまたはSQLSTATEを介して完了状態を返す。
  2. async_statement_identifierによって指定されたSQL文を参照することができなくなる。
以下のリクエスト タイプでは、TESTは実行できない。
  • DECLARE CURSOR文によって指定されるカーソル リクエスト。
  • PREPAREまたはEXECUTE IMMEDIATE文で指定された動的リクエスト。

例1 - 3

以下のRDTINフィールドは、これらの例において重要です。

RDTINフィールド 必須の指定
RdtCType 460に設定。
RdtVersn 10に設定。
RdtExt ’Y’に設定。拡張機能領域の存在を示す。
RdtXTotL RDTXASYN拡張機能領域のサイズを含む。

さらに、RdtX008 (RDTXASYN)構造は、接続名と通信するので、拡張機能領域のいずれかを組み込む必要があります。

例: 非同期文識別子の明示的な指定

この例では、明示的に指定された非同期文識別子を使用します。

   EXEC SQL TEST ASYNSTMT1 COMPLETION;

例1でC Preprocessor2によって生成される行

{
   static struct {
          SQLInt32 RdtCType;
          SQLInt16 RdtVersn;
          SQLInt16 RdtRfu1;
          char     RdtUserid[8];
          SQLInt32 RdtEntty;
          char     *RdtCA;
          char     *RdtDAIn;
          char     *RdtDAOut;
          char     *RdtSql;
          char     *RdtRtCon;
          SQLInt32 RdtAux1;
          SQLInt32 RdtAux2;
          char     RdtLCS;
          char     RdtComit;
          char     RdtRelse;
          char     RdtExt;
          char     RdtSepBT;
          char     RdtUCStm;
          char     RdtCmpat;
          char     RdtComp;
          SQLInt16 RdtXTotL;
          char     RdtXFill[2];
          struct {
                 SQLInt16 RdtXLen;
                 SQLInt16 RdtXType;
                 SQLInt32 RdtXCode;
                 } RdtX005;
          struct {
                 SQLInt16 RdtXLen;
                 SQLInt16 RdtXType;
                 SQLInt32 RdtXAsyC;
                 struct {
                        SQLInt16 RdtXAsyL;
                        char     RdtXAsyT[30];
                        } RdtXAsyS;
                 } RdtX008;
          } RDTIN011 =
  {460,9,0,{' '},0,0,0,0,0,0,0,0,'N','C','N','Y','N','N',' ','C'
  ,52,{' '},{8,5,255},{40,8,1,{9,'A','S','Y','N','S','T','M','T'
  ,'1',' ',' ',' ',' ',' ',' ',' ',' ',' ',' ',' ',' ',' ',' ',
  ' ',' ',' ',' ',' ',' ',' '}}};
...
   RDTIN011.RdtX008.RdtXAsyL = strlen(STMTNAMF);
   memcpy(RDTIN011.RdtX008.RdtXAsyT,STMTNAMF,strlen(STMTNAMF));
...
   }

例2

以下の例では、ホスト変数を使用して非同期文識別子を取得します。

   EXEC SQL TEST :STMTNAMV COMPLETION;

例2でC Preprocessor2によって生成される行

{
 static struct {
        SQLInt32 RdtCType;
        SQLInt16 RdtVersn;
        SQLInt16 RdtDec;
        char     RdtUserid[8];
        SQLInt32 RdtEntty;
        char     *RdtCA;
        char     *RdtDAIn;
        char     *RdtDAOut;
        char     *RdtSql;
        char     *RdtRtCon;
        SQLInt32 RdtAux1;
        SQLInt32 RdtAux2;
        char     RdtLCS;
        char     RdtComit;
        char     RdtRelse;
        char     RdtExt;
        char     RdtSepBT;
        char     RdtUCStm;
        char     RdtCmpat;
        char     RdtComp;
        SQLInt16 RdtXTotL;
        char     RdtXFill[2];
        struct {
               SQLInt16 RdtXLen;
               SQLInt16 RdtXType;
               SQLInt32 RdtXCode;
               } RdtX005;
        struct {
               SQLInt16 RdtXLen;
               SQLInt16 RdtXType;
               SQLInt32 RdtXAsyC;
               struct {
                      SQLInt16 RdtXAsyL;
                      char     RdtXAsyT[30];
                      } RdtXAsyS;
               } RdtX008;
        } RDTIN017 =
        {460,10,0,{' '},0,0,0,0,0,0,0,0,'N','B','N','Y','N','N',' ','C',
        52,{' '},{8,5,255},{40,8,1,}};
 RDTIN017.RdtX008.RdtXAsyS.RdtXAsyL = STMTNAMV.len;
 memcpy(RDTIN017.RdtX008.RdtXAsyS.RdtXAsyT,STMTNAMV.arr,STMTNAMV.len);
 RDTIN017.RdtCA = (char *)(&sqlca);
 RDTIN017.RdtRtCon = SQL_RDTRTCON;
 TDARDI(&RDTIN017);
 SQL_RDTRTCON = RDTIN017.RdtRtCon;
   }

例3

以下の例では、ホスト変数を使用して、固定長文字列として非同期文識別子を渡します。

   EXEC SQL TEST :STMTNAMF COMPLETION;

例3でC Preprocessor2によって生成される行

{
 static struct {
        SQLInt32 RdtCType;
        SQLInt16 RdtVersn;
        SQLInt16 RdtDec;
        char     RdtUserid[8];
        SQLInt32 RdtEntty;
        char     *RdtCA;
        char     *RdtDAIn;
        char     *RdtDAOut;
        char     *RdtSql;
        char     *RdtRtCon;
        SQLInt32 RdtAux1;
        SQLInt32 RdtAux2;
        char     RdtLCS;
        char     RdtComit;
        char     RdtRelse;
        char     RdtExt;
        char     RdtSepBT;
        char     RdtUCStm;
        char     RdtCmpat;
        char     RdtComp;
        SQLInt16 RdtXTotL;
        char     RdtXFill[2];
        struct {
               SQLInt16 RdtXLen;
               SQLInt16 RdtXType;
               SQLInt32 RdtXCode;
               } RdtX005;
        struct {
               SQLInt16 RdtXLen;
               SQLInt16 RdtXType;
               SQLInt32 RdtXAsyC;
               struct {
                      SQLInt16 RdtXAsyL;
                      char     RdtXAsyT[30];
                      } RdtXAsyS;
               } RdtX008;
        } RDTIN018 =
        {460,10,0,{' '},0,0,0,0,0,0,0,0,'N','B','N','Y','N','N',' ','C',
        52,{' '},{8,5,255},{40,8,1,}};
 RDTIN018.RdtX008.RdtXAsyS.RdtXAsyL = strlen(STMTNAMF);
 memcpy(RDTIN018.RdtX008.RdtXAsyS.RdtXAsyT,STMTNAMF,strlen(STMTNAMF));
 RDTIN018.RdtCA = (char *)(&sqlca);
 RDTIN018.RdtRtCon = SQL_RDTRTCON;
 TDARDI(&RDTIN018);
 SQL_RDTRTCON = RDTIN018.RdtRtCon;
   }

例1 -3

以下の例は、クライアント プログラミング コードのコンテキストがないTEST文のSQLテキストを表わしています。

例: 名前req_1で識別した文のテスト

この例では、req_1という名前で識別される文の完了状態をテストし、適切な例外コードまたは完了コードをSQLCODEまたはSQLSTATEに返します。

名前req_1は、async_statement_modifier変数を使ってASYNC句で定義されます。

    TEST req_1 COMPLETION

例: ホスト変数reqid_varで識別した文のテスト

この例では、ホスト変数:reqid_varで識別される文の完了状態をテストし、適切な例外コードまたは完了コードをSQLCODEまたはSQLSTATEに返します。

:reqid_var内に入る名前は、ASYN句でasync_statement_modifier 変数を使って定義されます。

    TEST :reqid_var COMPLETION

例: WAITでのTESTの使用

この例ではWAITとともにTESTを使用します。プログラムは非同期的に2つの更新リクエストそれぞれreq_1req_2)を作成し、req_1req_2の両方が完了するのを待ってから次に進みます。

TEST文はSQLCODEを監視します。req_1およびreq_2の両方から成功した完了コード (SQLCODE = 0)が返されるまでは、メイン プログラムの残りの部分に進みません。

いずれかのリクエストが未完了の場合(SQLCODE = -651)には、待機を続けます。

両方の文が完了したら、メイン プログラムは処理を続けます。

SQL以外の文は擬似コードであり、WAIT文とTEST SQL文がホスト メイン プログラム内でどのような位置に置かれるかをおおまかに例示します。

        ...
        EXEC-SQL
          ASYNC req_1
          UPDATE table_a
          SET a = :a;
        EXEC-SQL
          ASYNC req_2
          UPDATE table_b
          SET b = :b;
        ...
    100 EXEC-SQL
          WAIT req_1, req_2 COMPLETION;
        ...
        EXEC-SQL
          TEST req_1 COMPLETION;
       IF SQLCODE = -651 THEN GOTO 100
       IF SQLCODE = 0 THEN CONTINUE
        EXEC-SQL
          TEST req_2 COMPLETION;
       IF SQLCODE = -651 THEN GOTO 100
       IF SQLCODE = 0 THEN CONTINUE
        ...

関連トピック

  • 非同期リクエストの送信方法については、ASYNC文修飾子を参照してください。
  • 非同期リクエストの待機およびそのステータスのテストの方法については、WAITを参照してください。