dc_dam_read
形式
ANSI C ,C++の形式
#include <dcdam.h> int dc_dam_read(int damfd,struct DC_DAMKEY *keyptr,int keyno, char *bufadr,int bufsize,DCLONG flags)
K&R版 C の形式
#include <dcdam.h> int dc_dam_read(damfd,keyptr,keyno,bufadr,bufsize,flags) int damfd; struct DC_DAMKEY *keyptr; int keyno; char *bufadr; int bufsize; DCLONG flags;
機能
指定した論理ファイルから,指定した範囲のブロックを,参照または更新目的で入力します。
-
回復対象のDAMファイルの場合
排他する単位は,論理ファイルをオープンしたときの指定に従います。トランザクションの範囲でない処理からでも,dc_dam_read関数を呼び出せます。ただし,参照目的の入力に限り,排他の指定はできません。
複数のブロックを一括して指定した場合は,複数のブロックのうちで一つでもエラーが起こると,入力バッファにはブロックを入力しないでエラーを返します。このとき要求があったすべてのブロック排他は解除されます。
参照目的で入力したあとに,同じブロックに対して更新目的での入力要求をした場合に,この更新目的での入力でエラーが起こると,参照目的での入力の排他も解除されます。
トランザクション途中でブロックを更新する指定(DAMサービス定義のdam_update_block_over=flush)があっても,次のような場合には,DCDAMER_JNLOVでエラーリターンする場合があります。
-
一つのトランザクションブランチの中でDAMファイルのブロックを更新(dc_dam_rewrite関数)しないで,更新目的のブロック入力(dc_dam_read関数)をして,そのブロック数が一括更新最大ブロック数(DAMサービス定義のdam_update_blockオペランドの値)を超えた場合
回復対象のDAMファイルのブロックを入力する場合は,トランザクションの処理範囲からdc_dam_read関数を呼び出してください。
-
-
回復対象外のDAMファイルの場合
回復対象外のDAMファイルのブロックを入力する場合は,dc_dam_read関数を呼び出す条件に制限はありません。
回復対象外のDAMファイルに対して,DAMサービス定義のdam_update_blockオペランドに指定した値を超えて,更新目的のdc_dam_read関数を呼び出した場合は,DCDAMER_ACSOVでエラーリターンします。
論理ファイルのブロックを入力するときは,dc_dam_open関数で返されたリターン値のファイル記述子を設定します。
UAPで値を設定する引数
●damfd
ブロックを入力するファイルの,ファイル記述子を設定します。
●keyptr
参照または更新するブロックの範囲を示す構造体(DAMキー)のアドレスを設定します。構造体にはブロックの範囲を,先頭の相対ブロック番号と最後の相対ブロック番号で設定します。構造体の形式は次のとおりです。
struct DC_DAMKEY { int fstblkno; int endblkno; };
-
fstblkno
参照または更新するブロックの,先頭の相対ブロック番号を設定します。
-
endblkno
参照または更新するブロックの,最後の相対ブロック番号を設定します。0を設定した場合は,fstblknoで設定した相対ブロック番号のブロックだけを入力します。
●keyno
keyptrで設定する構造体の数(構造体の配列数)を設定します。
●bufadr
入力バッファのアドレスを設定します。
●bufsize
入力バッファ長を(入力ブロック長 × ブロック数)以上の値で設定します。設定できる範囲は504〜2147483647です。
●flags
参照要求か更新要求かの種別を設定します。次の形式で設定します。
{DCDAM_REFERENCE|DCDAM_MODIFY} 〔|{DCDAM_EXCLUSIVE|DCDAM_NOEXCLUSIVE}〕 〔|{DCDAM_WAIT|DCDAM_NOWAIT}〕
-
フラグ1
dc_dam_read関数で入力する種別(参照目的か更新目的か)を設定します。
DCDAM_REFERENCE…参照目的の入力。
DCDAM_MODIFY……更新目的の入力。
-
フラグ2
参照目的の入力の場合,排他をかけるかどうかを指定します。DCDAM_EXCLUSIVEを設定した場合は,同期点の処理まで排他をかけます。
トランザクションの外から回復対象のDAMファイルに参照目的でアクセスする場合は,排他する指定はできません。
フラグ2を省略した場合は,DCDAM_NOEXCLUSIVEが仮定されます。
排他をかけないでdc_dam_read関数を呼び出した場合,dc_dam_read関数の処理中にほかのUAPから該当するブロックが更新されることがあります。この場合,dc_dam_read関数で入力するブロックの内容は,ほかのUAPでの更新処理の状態に依存します。したがって,最新のブロックの内容を参照する場合には,必ずDCDAM_EXCLUSIVEを指定してください。
更新目的の入力の場合,フラグ2に値を設定できません(強制的にDCDAM_EXCLUSIVEとなります)。
DCDAM_EXCLUSIVE…排他をします。
DCDAM_NOEXCLUSIVE…排他をしません。
-
フラグ3
排他エラーが起こったとき,排他解除待ちをするかどうかを設定します。この値はDCDAM_NOEXCLUSIVEと同時には設定できません。
damfdに設定したファイル記述子のdc_dam_open関数が,排他種別にファイル排他を設定していた場合は,ここに設定する値は意味を持ちません。
DCDAM_WAIT…排他解除待ちをします。
DCDAM_NOWAIT…待たないで,エラーリターンします。
どちらも設定しなかった場合は次のようになります。
-
dc_dam_open関数でDCDAM_WAITを設定していれば,排他解除待ち
-
dc_dam_open関数でDCDAM_NOWAITを設定,または省略している場合はエラーリターン
flagsの値に設定したフラグと,排他の設定内容の対応を次に示します。
フラグ1 |
フラグ2※1 |
フラグ3※2 |
flagsの設定内容 |
---|---|---|---|
REFERENCE |
EXCLUSIVE |
WAIT |
参照目的,排他あり,排他エラー時は解除待ち |
NOWAIT |
参照目的,排他あり,排他エラー時はエラーリターン |
||
NOEXCLUSIVE |
× |
参照目的,排他なし※3 |
|
MODIFY |
× |
WAIT |
更新目的,排他エラー時は解除待ち |
NOWAIT |
更新目的,排他エラー時はエラーリターン |
- (凡例)
-
×:設定できません。
- 注※1
-
省略した場合は,NOEXCLUSIVEが仮定されます。
- 注※2
-
省略した場合は,dc_dam_open関数が設定した排他待ち種別の値に従います。
- 注※3
-
回復対象のDAMファイルの場合,トランザクションの範囲でない処理からdc_dam_read関数を呼び出すときは,フラグ1にDCDAM_REFERENCEを設定して,フラグ2にDCDAM_NOEXCLUSIVEを設定または省略したときだけ有効です。これ以外の値を設定してdc_dam_read関数を呼び出した場合は,DCDAMER_PROTOでエラーリターンします。
リターン値
リターン値 |
リターン値(数値) |
意味 |
---|---|---|
DC_OK |
0 |
すべてのブロック入力は正常に終了しました。 |
DCDAMER_PROTO |
-1600 |
dc_rpc_open関数を呼び出していません。 |
トランザクションの範囲外で,更新目的の入力,または排他を指定した参照目的の入力をしています(回復対象のDAMファイルにアクセスした場合だけリターンされます)。 |
||
ユーザサービス定義のatomic_updateオペランドの指定が'N'になっています(回復対象のDAMファイルにアクセスした場合だけリターンされます)。 |
||
dc_dam_start関数を呼び出していません(回復対象外のDAMファイルにアクセスした場合だけリターンされます)。 |
||
次に示すように,UAPを正しくリンケージしていません。
|
||
DCDAMER_EXCER |
-1602 |
排他エラーが起こりました。 |
DCDAMER_BADF |
-1603 |
damfdに設定したファイル記述子は正常にオープンして得られたファイル記述子ではありません。 |
DAMファイルをオープンしていません。 |
||
DCDAMER_BUFER |
-1604 |
すべてのブロックを入力するためには,入力バッファ長に設定した長さは不十分です。 |
入力バッファ長に設定した値は,設定できる範囲を超えています。 |
||
DCDAMER_BNOER |
-1606 |
相対ブロック番号が間違っています。 |
DCDAMER_NOMEM |
-1607 |
メモリが不足しました。 |
DCDAMER_PARAM_KEYNO |
-1609 |
keynoに1より小さい値を設定しています。 |
DCDAMER_PARAM_FLAGS |
-1611 |
flagsに指定した値が間違っています。 |
DCDAMER_JNLOV |
-1613 |
ブロック更新した回数※が,DAMサービス定義の1トランザクションで更新できる最大ブロック数に指定した値を超えました(回復対象のDAMファイルにアクセスした場合だけリターンされます)。 |
DCDAMER_VERSION |
-1618 |
UAPが,現在稼働しているDAMサービスでは動作できないバージョンのDAMライブラリと結合されています。 |
DCDAMER_IOER |
-1620 |
入力エラーが起こりました。 |
DCDAMER_LHOLD |
-1621 |
damfdに設定したファイル記述子のファイルが,論理閉塞されています。 |
DCDAMER_OHOLD |
-1622 |
damfdに設定したファイル記述子のファイルが,障害閉塞されています。 |
DCDAMER_ACCESS |
-1628 |
アクセスしようとしたDAMファイルは,セキュリティ機能で保護されています。dc_dam_read関数を呼び出したUAPには,アクセス権限がありません。 |
DCDAMER_TMERR |
-1629 |
トランザクションサービスでエラーが起こりました(回復対象のDAMファイルにアクセスした場合だけリターンされます)。 |
DCDAMER_DLOCK |
-1642 |
デッドロックが起こりました。 |
DCDAMER_TIMOUT |
-1643 |
ロックサービス定義で指定した待ち時間のタイムアウトのため,資源を確保できませんでした。 |
DCDAMER_LCKOV |
-1645 |
最大同時排他要求数を超えて,排他を要求しています。 |
DCDAMER_ACSOV |
-1648 |
回復対象外のDAMファイルにアクセスできるブロック数※を超えました(回復対象外のDAMファイルにアクセスした場合だけリターンされます)。 |
- 注※
-
詳細については,マニュアル「OpenTP1 システム定義」のDAMサービス定義のdam_update_blockオペランドを参照してください。
注意事項
リターン値DCDAMER_JNLOV,DCDAMER_ACSOVでリターンした場合,次のどれかの方法で処置してください。
-
DAMサービス定義のdam_update_blockオペランドの指定値を大きくする。
-
DAMサービス定義のdam_update_block_overオペランドにerrorを指定してDCDAMER_JNLOVとなった場合,dam_update_block_overオペランドの指定をflushに変更する。
-
更新目的で入力するブロック数をDAMサービス定義のdam_update_blockオペランドの指定値以下にする。
定義を変更する場合は,マニュアル「OpenTP1 システム定義」のDAMサービス定義のdam_update_blockオペランド,およびdam_update_block_overオペランドを参照し,注意事項を確認してください。