add

EGL add 文は、ファイル、メッセージ・キュー、またはデータベースの中にレコードを書き込みます。またはデータベースにレコード・セットを書き込みます。


add 文の構文図
record name
追加する入出力オブジェクトの名前。DLISegment レコード、索引付きレコード、MQ レコード、相対レコード、シリアル・レコード、SQL レコードなどを指定します
usingPCB pcbName
PCB 名を指定できるオプション。PSB レコードで定義するのと同じように、デフォルトの PCB 名の代わりに使用します。
with #dli{ dliStatement }
DL/I サポート』で説明されているように、明示的 DL/I ISRT 呼び出しを許可するオプション。#dli と左中括弧の間にスペースを入れないでください。
with #sql{ sqlStatement }
明示的な SQL INSERT 文を許可するオプション。#sql の後にスペースを入れないでください。
SQL dynamic array name
SQL レコードの動的配列の名前。各エレメントは、エレメント固有のキー値によって指定されるデータベース内の位置に挿入されます。 操作は、最初のエラー時に、またはすべてのエレメントが挿入されたときに停止します。

以下に例を示します。

	if (userRequest == "A")
		try
			add record1;
		onException
			myErrorHandler(12);
		end
	end

add 文の振る舞いは、レコード・タイプによって異なります。DL/I 処理の詳細については、『DLISegment レコード』を参照してください。 SQL 処理の詳細については、『SQL レコード』を参照してください。

DLISegment レコード

add 文は DL/I ISRT 文を生成します。DL/I では、この挿入はたとえそれがどこであろうと、データベース中の現行位置で起こります。この位置は、例えば、set record position 文を使用することにより、get 文を使用することにより、または修飾された SSA を #dli ディレクティブで作成することにより、ご使用の EGL プログラムのキーを (下記の例に示すように) 明示的に設定することによって、制御できます。

次の例は顧客データベースにオーダーを追加します
	//レコードのインスタンスを作成する
	myCustomer CustomerRecord;
	myLocation LocationRecord;
	myOrder    OrderRecord;

	//セグメント検索引数を作成する
	myCustomer.customerNo = "005001";
	myLocation.locationNo = "000022";

	//オーダー・レコードのフィールドに書き込む
	fillOrder(myOrder);
	
	//新規のオーダー・レコードを追加する
	try
		add myOrder;
		onException
			myErrorHandler(2);
	end
この add 文から次の擬似 DL/I コードが生成されます。
ISRT STSCCST (STQCCNO = :myCustomer.customerNo) 
     STSCLOC (STQCLNO = :myLocation.locationNo) 
     STPCORD
顧客とロケーションに関する修飾セグメント検索引数 (SSA) は、新規のオーダー・セグメントの親セグメントを識別します。 DL/I は、そのセグメントの keyItem フィールド、orderDateNo (STQCODN) によって決定される位置に新規のオーダー・セグメントを追加します。
「noRecordFound」のような「ソフト側」の入出力エラーを取り込むには、プログラムを作成するときに set-values ブロックを使用してプログラム・プロパティー throwNrfEofExceptions を yes に設定します。エラー・ハンドラー関数で「is」または「not」演算子を使い、エラーの有無をテストします。
	if (myOrder is unique)
		...
	end
考えられるランタイム・エラーには次のものがあります。
  • オーダー・セグメントが既に指定されたキーによって存在している場合に固有 (複製は許可されない)
  • オーダー・セグメントが同じキーによって存在している場合に複製であるが、複製が許可されている
DL/I では add 文に対するパス呼び出しの使用もサポートしています。 これは、追加している最も低いレベルのセグメントとルート間にあるすべてのセグメントに対して親セグメントを追加できることを意味しています。 次の例で、 DL/I は新しいオーダーを追加すると同時に新しい顧客とロケーションを追加します。
add myCustomer, myLocation, myOrder;
EGL はこの文から次の擬似 DL/I コードを生成します。
ISRT STSCCST*D (STQCCNO = :myCust.customerNo) 
     STSCLOC (STQCLNO = :myLocation.locationNo) 
     STPCORD

索引付きレコード

索引付きレコードを追加するときは、レコード内のキーによって、ファイル内でのレコードの論理位置が判別されます。 既に使用されているファイル位置にレコードを追加すると、 ハード入出力エラー UNIQUE、または (重複が許可されている場合は) ソフト入出力エラー DUPLICATE になります。

MQ レコード

MQ レコードを追加するとき、レコードはキューの最後に入れられます。 この追加処理は、add 文で以下に示す 1 つ以上の MQSeries® 呼び出しが呼び出されることによって行われます。

相対レコード

相対レコードを追加するときは、キー項目によって、ファイル内でのレコードの位置が指定されます。 ただし、既に使用されているファイル位置にレコードを追加すると、 ハード入出力エラー UNIQUE になります。

レコード・キー項目は、そのレコードを使用するすべての関数で使用できなければなりません。以下のいずれかをレコード・キー項目とすることができます。
  • 同じレコード内の項目
  • プログラムに対してグローバルであるか、または add 文を実行している 関数に対してローカルであるレコード内の項目
  • プログラムに対してグローバルであるか、または add 文を実行している 関数に対してローカルであるデータ項目

シリアル・レコード

シリアル・レコードを追加するとき、レコードはファイルの末尾に入れられます。

生成されたプログラムでシリアル・レコードが追加されてから、 同じファイルに対して get next 文が発行されると、 get next 文が実行される前に、 ファイルが閉じられてから再び開かれます。 したがって、add 文の後に実行される get next 文では、ファイル内の最初のレコードが読み取られます。この振る舞いは、get next 文と add 文が別々のプログラムにあり、一方のプログラムで他方のプログラムが呼び出される場合にも起こります。

複数のプログラムで同時に同じファイルが開かないようにしておくことをお勧めします。

CICS® for z/OS® では、同じスプール・ファイルに関する add 文と get next 文を組み合わせて 1 つのプログラムに組み込むことはできません。 この制限は、add 文と get next 文が別々のプログラムにあり、一方のプログラムが他方のプログラムを呼び出す場合にも適用されます。同様に、get 文または get next 文 に続く add 文は、ファイルの先頭にレコードを追加します。

IMS™ BMP または z/OS バッチでは、GSAM と関連付けられたファイルに可変長のシリアル・レコードを追加した場合に、レコード長が物理ファイルよりも長いときには、DL/I は空白の状況コードを戻します。 データは切り捨てられますが、状況は検出できないのでメッセージは発行されません。

IMS/VS では、シリアル・レコードを代替 PCB (PSB 中の TP PCB) に関連付ける必要があります。IMS のメッセージ・ヘッダー (長さ、ZZ フィールド、およびトランザクション・コード) は、メッセージ・キューに書き込まれた各レコードに自動的に追加されます。 メッセージ・キューに割り当てられたシリアル・レコードに関する EGL の add 文の結果、メッセージ・キューへの ISRT 呼び出しが行われます。エラーが発生し、レコードが複数セグメントのメッセージ・キューに割り当てられて特別代替 PCB と関連付けられると、既に追加されていたすべてのレコードは、明示的な close 文がなくてもコミットされます。 これらのレコードがコミットされないこと、新たな明示代替 PCB を PSB 中に含めること、およびファイルを追加の明示代替 PCB と関連付けることが大切です。

SQL レコード

エラー条件は、以下のとおりです。
  • INSERT 以外の型の SQL 文を指定する
  • SQL INSERT 文の全部ではなく一部の文節を指定する
  • 以下のいずれかの特性を持つ SQL INSERT 文を指定する (または暗黙的な SQL 文を受け入れる)
    • 複数の SQL テーブルに関連付けられている
    • 読み取り専用として宣言したホスト変数のみを組み込む
    • 存在しないか、関連するホスト変数との互換性がない列に関連付けられている
明示的 SQL 文を指定しないで SQL レコードを追加すると、結果は以下のようになります。
  • 生成される SQL INSERT 文の形式は、以下のようになります。
      INSERT INTO tableName
        (column01, ... columnNN)
        values (:recordItem01, ... :recordItemNN)
  • テーブル内でのデータの論理位置は、レコード内のキー値によって判別されます。 キーを持たないレコードは、SQL テーブルの定義とデータベースの規則に従って処理されます。
  • レコード・パーツにおけるレコード項目と SQL テーブルの列の関連付けの結果、生成されたコードにより、関連する SQL テーブル列に各レコード項目のデータが格納されます。
  • レコード項目が読み取り専用として宣言されている場合、 生成された SQL INSERT 文にはそのレコード項目が含まれず、 データベース管理システムでは、関連する SQL テーブル列の値がデフォルト値 (その列が定義されたときに指定された値) に設定されます。
SQL レコードの動的配列を使用する例は、以下のとおりです。
  try
    add employees;
    onException
      sysLib.rollback();
  end
フィードバック
(C) Copyright IBM Corporation 2000, 2005. All Rights Reserved.