NOTIFY - Basic Teradata Query

目的

この制御によって、ユーザーは、特定の重要なイベントが発生したときに、ユーザー出口または事前定義アクションを指定できます。NOTIFYは、直後のSQLリクエストにのみ適用されます。

NOTIFYコマンドは、システム性能を最適化するためにジョブのスケジューリングが自動化されていて、オペレータの介入がない環境で使用されます。 BTEQのジョブ ストリームを自動化するためのフックが含まれているので、プログラマは、それらのフックを使用することにより、BTEQのジョブ ストリームとサード パーティのベンダーが提供するプロダクトを、BTEQスクリプトの出力を解析することなく統合することができます。

例えば、Cで出口を記述(CLIv2は未使用)し、NOTIFY...EXITオプションを使用することで、プログラマは、要求の成功または失敗、要求が成功した場合に返されたブロック数、および要求が失敗した場合の戻りコードなどを検出できる手段を、自動化パッケージ用に作成できます。

構文

次のような場合に当てはまります。

EXIT

ユーザーが記述する出口が、必要に応じて呼び出される。 冗長度が高い場合、ユーザー出口機能に渡されるアクティビティ カウントは符号無し32ビット値に、要求カウントは符号付き32ビット値になります。

EXIT64

ユーザーが記述する出口が、必要に応じて呼び出される。 冗長度が高い場合、ユーザー出口機能に渡されるアクティビティ カウントおよび要求カウントは符号無し64ビット値として定義されます。

HIGH

すべてのイベントに対して通知が発行される

LOW

1つのイベントに対してのみ通知が発行される

このオプションは、EXIT、EXIT64、MSG、QUEUEの各オプションと共に使用されます。

MEDIUM

ユーザーの関心事である次のようなときに通知が発行される。

• ジョブが終了したとき
• 重大なイベントが発生したとき

MSG

メッセージは次のデバイスまたはファイルに書き込まれる。

• オペレータ コンソール(z/OS)
• システム ログ(UNIX OS)
• EventLogサービス(Windows)

name

_dynamnというエントリ ポイントを持つユーザー提供のライブラリの名前を指定する。

ライブラリの名前は、オペレーティング システムによって異なります。 ユーザー ルーチンは、C言語か、Cと互換性のある実行時環境を持つ言語で記述する必要があります。

OFF

イベントの通知は含まれない。

これはデフォルトです。

options

次のz/OS QUEUEパラメータ オプションのうちいずれか。

• RNAME – 引用符で囲んだ文字列(最大255バイト)。 デフォルトはTRDUSER。
• SCOPE –
SYSTEMS:QUEUEは、複合体内のすべてのコンピュータでアクセスできる。 これは、デフォルト値です。
SYSTEM:QUEUEは、実行されているコンピュータでアクセスできる。
JOB:QUEUEは、そのジョブ(すべてのジョブ ステップを含む)がアクセスできる。
• NOBLOCK - 何らかの理由でENQがブロックする場合にエラーが返されるように指定する。 これは、ジョブの致命的エラーとなります。

QUEUE

ENQまたはDEQによって待ち行列が操作されるよう指定する。詳細については、この節の後の部分のQUEUEについての注記を参照してください。

このオプションは、z/OSの場合にのみ有効です。

text

出力メッセージに含められる254バイト識別文字列を指定する。 254バイトより長い場合は、切り捨てられます。 z/OSでは、このフィールドは134バイトに制限されるので注意してください。これはJESジョブ ログのサイズです。 JESジョブ ログには、日付、ジョブ番号、BTEQのメッセージ(MSGテキストおよびイベント通知テキストを含む)が格納されます。

使用方法に関する注意

NOTIFYは、SET DEFAULTの影響を受けません。

SHOW CONTROLSコマンドを使用して、現在のNOTIFY値を表示できます。

NOTIFYコマンドは、Teradata SQLマクロでは使用できません。

EXITオプションを使用したときユーザー出口に渡されるアクティビティ カウント値のデータ型はUInt32 (符号なし32ビット整数)です。EXIT64オプションを使用したときはUInt64 (符号なしビット整数)です。 同様に、EXITオプションを使用したときユーザー出口に渡される要求カウント値はInt32(符号付き32ビット整数)です。EXIT64オプションを使用したときはUInt64(符号無し64ビット整数)です。 EXITオプションを使用した場合、非常に大きなアクティビティ カウント値または要求カウント値が切り捨てられる場合があります。

ユーザー テキストをユーザー出口モジュールに渡すためには、NOTIFY EXIT/EXIT64コマンドの直前で、NOTIFY MSGコマンドを使用します。例えば、次のようになります。

.SET NOTIFY HIGH MSG ‘user-text’

.SET NOTIFY HIGH EXIT btnfyext

このユーザー テキストは、その次のNOTIFY MSGコマンドが実行されるまで有効なままになります。その結果、すべてのユーザー出口が同じユーザー テキストを受け取ることになります。 NOTIFY MSGコマンドで設定されたユーザー テキストを表示するためには、SHOW CONTROLSコマンドを使用します。

前の処置の結果をリセットするためには、textを指定せずにNOTIFY MSGコマンドを使用します。

次のテーブルは、NOTIFYのイベントとそのイベント固有の番号を示しています。

QUEUEについての注記

• NOTIFYが処理されると、RNAMEが'TRDUSER'で有効範囲が'SYSTEMS'のQUEUEで、ENQが実行されます。 QUEUEが取得されるまで、呼び出しは実行されません。
• ジョブがQUEUEを得た後、ジョブは特定の時点(要求の完了など)に達するまで続行し、それからDEQの実行によってQUEUEを解放します。

エラー処理に関する注記

再始動に関する注記

アプリケーションが異常終了または失敗した場合は、アプリケーションを再始動することができ、NOTIFYに関連する活動も再度実行されます。 ユーザー出口を記述する場合は、この点に注意する必要があります。

アプリケーションが待ち行列を保持しているときに異常終了または失敗終了する場合(z/OSで、QUEUEパラメータを指定)、アプリケーションは、待ち行列を解放してからジョブを終了します。 したがって、ジョブを再始動する場合には、待ち行列を取得してから処理を続行する必要があります。

出口モジュールの作成

次のテーブルは、それぞれのオペレーティング システムを使用した出口モジュールの作成方法を要約したものです。

cp “//’USER.SAMPLIB(BTNFYEXT)‘” btnfyext.h
cp “//’USER.SAMPLIB(BTNFYXTC)‘” btnfyext.c
cc -o “//’USER.LOAD(BTNFYEXT)’” -W c,dll,expo -W l,dll btnfyext.c

NOTIFYの例

UNIXでのNOTIFYの例

例1 – UNIX

この例では、ユーザーがロードできるbtnfyext.soというモジュールを使用しています。 このモジュールは、makefileと共に例としてBTEQに付属するファイルbtnfyext.cから作成されたものです。

BTEQを呼び出す前に、環境変数のLD_LIBRARY_PATHを設定してモジュールを見つけることができるようにしています。

Script started on Wed Jan 24 18:19:12 1996
app002-0:/home/cme/src/notify/clientsw/src/bteqsrc > export 
LD_LIBRARY_PATH=/home/cme/src/notify/clientsw/src/bteqsrc
app002-0:/home/cme/src/notify/clientsw/src/bteqsrc > bteq
 Teradata BTEQ 3.1 for UNIX5. Enter your logon or BTEQ command:
.logon dbc
....
 
 BTEQ -- Enter your SQL request logon or BTEQ command:
.set notify low exit btnfyext.so
.set notify low exit btnfyext.so
 BTEQ -- Enter your SQL request logon or BTEQ command:
sel * from sessiontbl;
sel * from sessiontbl;
 *** Query completed. 5 rows found. 24 columns returned.
 *** Total elapsed time was 1 second.
 HostNo      SessionNo IFPNo LogonDate   LogonTime LogonCollation LogonData
------- -------------- ----- --------- ----------- -------------- ----
     97             -2   4-3  96/01/24 15:25:29.56 H              TDPUSER
     93             -2   3-4  96/01/09 17:13:25.24 H              TDPUSER
    100          1,012   4-4  96/01/24 18:22:18.20 H              DBC
     93             -3   3-4  96/01/09 17:13:25.25 H              TDPUSER
     97             -3   3-3  96/01/24 15:25:29.57 H              TDPUSER
.....

ユーザーがロード可能なモジュールでは、NFYEXT.OUTというファイルに渡されたパラメータが書き込まれます。 パラメータ シーケンスの後、ファイルには次の1行が含まれます。

exit called @ bteq request complete.

例2 – UNIX

この例では、MEDIUMオプションを使用しています。 BTEQの出力については、使用例1と同じなので省略されています。

NFYEXT.OUT出力ファイルには、次の2行が含まれます。

exit called @ bteq request complete.
exit called @ bteq notify out of scope: return code 0.

例3 – UNIX

この例では、HIGHオプションを使用しています。 すべてのイベントが使用され、exit(退出)が6回呼び出されます。

exit called @ bteq init.
	     Version Id:	Notify Version 01.00.00.
	     Version Id Len:	23.
	     Utility Id:	4.
	     Utility Name:	BTEQ 14.00.00.00.
	     Utility Name Len: 16.
	     User Name:	dbc.
	     User Name Len:	3.
exit called @ bteq start request: 'sel * from sessiontbl;'.
exit called @ bteq request complete.
exit called @ bteq fetch: statement 1, request 1 activity 5.
exit called @ bteq request processing complete: 1 requests
exit called @ bteq notify out of scope: return code 0.

例4 – UNIX

この例では、MSGオプションを使用しています。

BTEQからの標準出力を、次に示します。

BTEQ 3.1 Wed Jan 24 20:05:10 1996
 
+---------+---------+---------+---------+---------+----
.logon dbc,
 *** Logon successfully completed.
 *** Transaction Semantics are BTET.
 *** Character Set Name is ASCII.
 *** Total elapsed time was 1 second.
 
+---------+---------+---------+---------+---------+----
.set notify high msg 'This is a UNIX msg';
+---------+---------+---------+---------+---------+----
sel * from sessiontbl;
*** Query completed. 5 rows found. 24 columns returned.
 *** Total elapsed time was 1 second.
 HostNo SessionNo IFPNo LogonDate   LogonTime LogonCollation LogonData
------- --------- ----- --------- ----------- -------------- ---------
    97         -2   4-3  96/01/24 15:25:29.56 H              TDPUSER
    93         -2   3-4  96/01/09 17:13:25.24 H              TDPUSER
    93         -3   3-4  96/01/09 17:13:25.25 H              TDPUSER
   100      1,013   4-4  96/01/24 20:02:59.95 H              DBC
    97         -3   3-3  96/01/24 15:25:29.57 H              TDPUSER
+-----+--------_-+------+---------+-----------+-----------------------
.quit
 *** You are now logged off from the DBC.
 *** Exiting BTEQ...
 *** RC (return code) = 0

UNIXシステムでは、MSGオプションは、標準のsyslog(システム ログ)システムを使用してメッセージを書き込むように求めます。

テスト システムでは、ファイルのデフォルト位置は/var/adm/usererr/
error.01-24になります。 ただし、この位置は変わることがあります。

前のジョブが実行されると、システム ログに次の行が出力されます。

Jan 24 20:05:10 app002-0 unix: syslog: This is a UNIX msg - BTEQ notify processed.
Jan 24 20:05:10 app002-0 unix: syslog: This is a UNIX msg - BTEQ request issued: 'sel * from sessiontbl;'.
Jan 24 20:05:11 app002-0 unix: syslog: This is a UNIX msg - BTEQ request complete.
Jan 24 20:05:11 app002-0 unix: syslog: This is a UNIX msg - BTEQ ready to fetch request 1, statement 1: activity count 5.
Jan 24 20:05:11 app002-0 unix: syslog: This is a UNIX msg - BTEQ fetches complete: 1 requests.
Jan 24 20:05:11 app002-0 unix: syslog: This is a UNIX msg - BTEQ notify out of scope RC = 0.

NOTIFYのz/OSの例

例1 – z/OS

この例では、ENQUEUE/DEQUEUEの機能を使用しています。この機能は、z/OSでのみサポートされています。

SYSPRINTを、次に示します。

********************** TOP OF DATA *******************************
TERADATA CORPORATION            BTEQ 5.3.0 Thu Jan 18 15:03:41 1996
                                                                                
+---------+---------+---------+---------+---------+----
/***************************************/
/* just a little test program...       */
/***************************************/
.WIDTH 80
+---------+---------+---------+---------+---------+----
.LOGON tdri/cme,
 *** Logon successfully completed.
                                          
 *** Total elapsed time was 0.75 seconds.
                                        
+---------+---------+---------+---------+---------+----
.show versions;
 BTEQ Version 5.3.0 for IBM OS/370
 BTQMain   : H3_03
 BTQUtil   : H3_05
 BTQResp   : H3_03
 BTQParse  : H3_02
 BTQNotfy  : H3_00
 CapAAUtl  : H3_01
 CapCLUtl  : H3_02
 CapIOUtl  : H3_03
 CapLogW   : H3_00
 CapMVSQ   : H3_00
 CapNfy    : H3_00
 CapLoadM  : H3_00
 MOSIDEP   : H0_02
 CapTypes  : H2_01
 CapDBC    : H3_00
 ITBDBC    : H3_02
 MOSIIF    : H2_01
 BTEQ linking date is 01/03/96
+---------+---------+---------+---------+---------+----
.set notify low queue rname 'sighsighsighsigh';
+---------+---------+---------+---------+---------+----
.if errorcode <> 0 then .quit errorcode;
+---------+---------+---------+---------+---------+----
sel * from cme.foo;
 *** Query completed. 4 rows found. One column returned.
 *** Total elapsed time was 0.27 seconds.
96/01/18                      sel * from cme.foo;                     Page    1
                                            a
                                  -----------
                                            2
                                            4
                                            1
                                            3
+---------+---------+---------+---------+---------+----
.LOGOFF
 *** You are now logged off from the DBC.
+---------+---------+---------+---------+---------+----
 *** Exiting BTEQ...
 Ending BTEQ  Thu Jan 18 15:03:42 1996

例2 – z/OS

この例では、MSGオプションを使用しています。

SYSPRINTを、次に示します。

TERADATA CORPORATION            BTEQ 5.3.0 Thu Jan 18 15:05:11 1996
                                                    
+---------+---------+---------+---------+---------+----
/***************************************/
/* just a little test program...       */
/***************************************/
.WIDTH 80
+---------+---------+---------+---------+---------+----
.LOGON tdri/cme,
 *** Logon successfully completed.
                                                                                
 *** Total elapsed time was 0.65 seconds.
                                                  
+---------+---------+---------+---------+---------+----
.set notify low msg 'this is a test' ;
+---------+---------+---------+---------+---------+----
.if errorcode <> 0 then .quit errorcode;
+---------+---------+---------+---------+---------+----
sel * from cme.foo;
 *** Query completed. 4 rows found. One column returned.
 *** Total elapsed time was 0.17 seconds.
96/01/18                      sel * from cme.foo;                    Page    1
                                            a
                                  -----------
                                            2
                                            4
                                            1
                                            3
+---------+---------+---------+---------+---------+----
.LOGOFF
 *** You are now logged off from the DBC.
+---------+---------+---------+---------+---------+----
 *** Exiting BTEQ...
 Ending BTEQ  Thu Jan 18 15:05:12 1996
                                        

JES2 LOGの出力は、次のようになります。 TRDF0010IメッセージはMSGの出力であり、ユーザーが指定した文字列"this is a test"が含まれています。

J E S 2  J O B  L O G  --  S Y S T E M  M V S 2  --  N O D E  T E R M V S 2
15.05.06 JOB 3214  $HASP373 BTEQTEST STARTED - INIT 42 - CLASS A - SYS MVS2
15.05.11 JOB 3214  +TRDF0010I this is a test - BTEQ request complete.'
15.05.12 JOB 3214  BTEQTEST.STEP01  .         RC=ZERO T=0000 D=0214 MT=.16S ET=5.5S
15.05.12 JOB 3214  BTEQTEST ENDED.  NAME=CHARLES EUBANKS      TOTAL MT=.16S ET=5.6S
15.05.12 JOB 3214  $HASP395 BTEQTEST ENDED
------ JES2 JOB STATISTICS ------
    18 JAN 96 JOB EXECUTION DATE
           38 CARDS READ
          182 SYSOUT PRINT RECORDS
            0 SYSOUT PUNCH RECORDS
            9 SYSOUT SPOOL KBYTES
         0.10 MINUTES EXECUTION TIME

例3 – z/OS

次の例は、SAS/C通知出口ロード モジュールの作成方法を示します。

また、サンプル通知CファイルBTNFYXTCおよびサンプル通知HファイルBTNFYEXTがUSER.SAMPLIB PDS内に存在し、次のJCLを使用して、SAS/Cコンパイラによるサンプル通知ロード モジュールUSER.LOADM (BTNFYEXT)の作成を実行できると仮定します。

//************************************************************
//* ACTN: COMPNFY - JCL for compiling.
//************************************************************
//COMPNFY  EXEC PGM=LC370B
//STEPLIB  DD DSN=SYS2.SASLIB.LOAD,DISP=SHR
//         DD DSN=SYS2.SASLIB.LINKLIB,DISP=SHR
//SYSTERM  DD SYSOUT=*
//SYSPRINT DD SYSOUT=*
//SYSUT1   DD UNIT=SYSDA,SPACE=(TRK,(10,10))
//SYSLIB   DD DSN=SYS2.SASLIB.MACLIBC,DISP=SHR
//H        DD DSN=USER.SAMPLIB,DISP=SHR
//SYSLIN   DD DSN=USER.TEXTM(BTNFYEXT),DISP=SHR
//SYSIN    DD DSN=USER.SAMP(BTNFYXTC),DISP=SHR
//*
//************************************************************
//* ACTN: COOLNFY - JCL for pre-linking object file.
//************************************************************
//COOLNFY  EXEC CMCOOL#,SREL=700C
//SYSLIN   DD  DISP=OLD,DSN=USER.OBJM(BTNFYEXT)
//SYSIN    DD  DISP=SHR,DSN=USER.TEXTM(BTNFYEXT)
//*
//************************************************************
//* ACTN: LINKNFY - JCL for linking object file.
//************************************************************
//LINKNFY  EXEC PGM=IEWL,PARM='LIST,MAP,XREF,LET,RMODE=24,AMODE=31'
//SYSPRINT DD  SYSOUT=*
//SYSUT1   DD  UNIT=SCR,SPACE=(CYL,(2,2))
//SYSUT2   DD  UNIT=SCR,SPACE=(CYL,(2,2))
//SYSLIN   DD  DSN=USER.OBJM(BTNFYEXT),DISP=SHR
//         DD  DDNAME=SYSIN
//SYSLIB   DD  DISP=SHR,DSN=SYS2.SASC700C.STDLIB
//         DD  DISP=SHR,DSN=SYS2.SASC700C.BASELIB
//SYSLMOD  DD  DSN=USER.LOADM(BTNFYEXT),DISP=SHR
//SYSIN    DD  DATA,DLM='##'
NAME BTNFYEXT(R)
##

例4 – z/OS

次の例は、JCLを使用したIBM/C通知出口ロード モジュールの作成方法を示します。

サンプル通知CファイルBTNFYXTCおよびサンプル通知HファイルBTNFYEXTがUSER.SAMPLIB PDS内に存在し、次のJCLを使用して、IBM/Cコンパイラによるサンプル通知出口ロード モジュールUSER.LOAD (BTNFYEXT)の作成を実行できると仮定します。

//BNFYIBMC EXEC EDCCL,
//* THE SAMPLE NOTIFY EXIT C-PROGRAM BTNFYXTC.C
//         INFILE='USER.SAMPLIB(BTNFYXTC)',
//* THE OUTPUT NOTIFY EXIT LOAD MODULE
//         OUTFILE='USER.LOAD(BTNFYEXT),DISP=SHR',
//         CPARM='DLL,RENT,LONGNAME,SOURCE,EXPO',
//         LPARM='DYNAM=DLL'
//* THE LOCATION OF REQUIRED HEADER FILE BTNFYEXT.H
//SYSLIB   DD DSN=USER.SAMPLIB,DISP=SHR
//*

WindowsでのNOTIFYの例

例1 – Windows

この例では、ユーザーがロードできるbtnfyext.dllというモジュールを使用しています。 このモジュールは、makefileと共に、例としてBTEQに付属するファイルbtnfyext.cから作成されたものです。

c:\program files\teradata\client\14.10\bin>bteq
Teradata BTEQ 14.10.00.00 for WIN32.
Copyright 1984-2012, Teradata Corporation. ALL RIGHTS RESERVED.
Enter your logon or BTEQ command:
.logon dbc
.logon dbc
Password:
***Logon successfully completed.
***Teradata Database Release is 14.10.00.00
***Teradata Database Version is 14.10.00.00
***Transaction Semantics are BTET.
***Character Set Name is ASCII.
***Total elapsed time was 2 seconds.
BTEQ -- Enter your SQL request or BTEQ command:
.set notify low exit64 btnftext.dll
BTEQ -- Enter your SQL request or BTEQ command:
sel * from dbc.sessioninfo;
***Query completed. 7 rows found. 15 columns returned.
***Total elapsed time was 1 second.
 username      AccountName      Session 
DBC          DBC             1,2
DBC          DBC             1,2
DBC          DBC             1,2
DBC          DBC             1,0
DBC          DBC             1,2
DBC          DBC             1,2
DBC          DBC             1,2

ユーザーがロード可能なモジュールでは、NFYEXIT.OUTというファイルに渡されたパラメータが書き込まれます。 パラメータ シーケンスの後、ファイルには次の1行が含まれます。

exit called @ bteq init.

例2 – Windows

この例では、MEDIUMオプションを使用しています。 BTEQの出力については、使用例7と同じなので省略されています。

NFYEXIT.OUT出力ファイルには、次の2行が含まれます。

exit called @ bteq request complete
exit called @ bteq notify out of scope: return code 0

例3 – Windows

この例では、HIGHオプションを使用しています。 すべてのイベントが使用され、出口モジュールが6回呼び出されます。

exit called @ bteq init.
	Version Id:	Notify Version 01.00.00.
	Version ID Len:	23.
	Utility Id:	4.
	Utility Name:	BTEQ 14.00.00.00.
	Utility Name Len:	16.
	User Name:	weekly.
	User Name Len:	6.
exit called @ bteq start request: 'sel * from dbc.sessioninfo;'.
exit called @ bteq request complete.
exit called @ bteq fetch: statement 1, request 1 activity 7.
exit called @ bteq request processing complete: 1 requests.
exit called @ bteq notify out of scope: return code 0.

例4 – Windows

この例では、MSGオプションを使用しています。 BTEQからの標準出力を、次に示します。

c:\teradata\bin>bteq
Teradata BTEQ 04.00.01.00 for WIN32. Enter your logon or BTEQ command:
.logon weekly
.logon weekly
Password:
***Logon successfully completed.
***Transaction Semantics are BTET.
***Character Set Name is ASCII.
***Total elapsed time was 41seconds.
BTEQ -- Enter your SQL request logon or BTEQ command:
.set notify high msg 'this is a NT msg';
.set notify high msg 'this is a NT msg';
BTEQ -- Enter your SQL request logon or BTEQ command:
sel * from dbc.sessioninfo;
sel * from dbc.sessioninfo;
***Query completed. 7 rows found. 15 columns returned.
***Total elapsed time was 9 seconds.
 username      AccountName      Session 
WEEKLY       DBC             1,0
WEEKLY       DBC             1,2
WEEKLY       DBC             1,2
WEEKLY       DBC             1,2
WEEKLY       DBC             1,2
WEEKLY       DBC             1,2
WEEKLY       DBC             1,2
BTEQ -- Enter your SQL request logon or BTEQ command:
quit;
quit;
***You are now logged off from the DBC.
***Exiting BTEQ...
***RC (return code) = 0

WindowsでMSGオプションを使用するには、イベントがメッセージ付きでEventLogサービスに送られる必要があります。 つまり、メッセージが捕捉されてアプリケーション ログを通してイベント ビューアで表示することができます。