ACSAPI
ACSAPIは、ACS(Application Control Support system)アプリケーションプログラムでメッセージを処理するための機能です。本付録では、現在OpenFrame AIMがサポートしているACSAPIの各コマンドと使用方法について説明します。
1. MSGGET
MSGGETはワークステーションで入力されたメッセージを受信するコマンドとして、受信メッセージがアプリケーションプログラムの入力メッセージ領域に通知されます。
以下は、ACSAPIコマンドの使用例です。
WORKING-STORAGE SECTION. 01 SYNC-DCOM. COPY COBSDCOM. 01 IN-DATA. 02 FILLER PIC S9(5) COMP VALUE 128. 02 FILLER PIC S9(5) COMP VALUE 0. 02 DATA PIC X(128). COPY CBACSAPI. 01 ACSSPA PIC X(128). ... PROCEDURE DIVISION. CALL 'ACSAPI' USING MSGGET SYNC-DCOM IN-DATA ACSSPA.
-
呼び出し形式
CALL 'ACSAPI' MSGGET, DCOM, 入力メッセージ領域[, ACSSPA].
-
パラメータ
以下は、MSGGETコマンドを使用する場合に設定するパラメータの説明です。
パラメータ 説明 MSGGET
MSGGETコマンドのマクロ値である「MSGGET」を指定します。
DCOM
アプリケーションプログラムのAPI通信領域としてSYNC-DCOMとASYNC-DCOMのいずれかを指定します。
-
SYNC-DCOM : 制御権がある通信の場合に指定します。アプリケーションプログラムに必ず1つ以上含める必要があります。
-
ASYNC-DCOM : 制御権がない通信の場合に指定し、必要なだけ記述します。
入力メッセージ領域
AIMから受信したデータを格納するメッセージ領域名を指定します。
SPA
SYNC-DCOMを使用する場合、SPAデータを格納する領域名を指定します。
-
SYNC-DCOMの場合、SPA領域は省略できます。
-
ASYNC-DCOMの場合、SPA領域を指定できません。
-
2. MSGPUT
MSGPUTは、アプリケーションプログラムで処理したメッセージをワークステーションに送信するコマンドです。アプリケーションプログラムの出力メッセージ領域に格納された内容がワークステーションに出力されます。
以下は、MSGPUTコマンドの使用例です。
WORKING-STORAGE SECTION. 01 SYNC-DCOM. COPY COBSDCOM. 01 OUT-DATA. 02 FILLER PIC S9(5) COMP VALUE 128. 02 FILLER PIC S9(5) COMP VALUE 0. 02 DATA PIC X(128). COPY CBACSAPI. 01 ACSSPA PIC X(128). ... PROCEDURE DIVISION. MOVE SPACE TO SMODE OF SYNC-DCOM. MOVE SPACE TO OPTC OF SYNC-DCOM. MOVE 'FMT001' TO FMID OF SYNC-DCOM. CALL 'ACSAPI' USING MSGPUT SYNC-DCOM OUT-DATA ACSSPA.
-
呼び出し形式
CALL 'ACSAPI' MSGPUT, DCOM, 出力メッセージ領域[, ACSSPA].
-
パラメータ
以下は、MSGPUTコマンドを使用する場合に設定するパラメータの説明です。
パラメータ 説明 MSGPUT
MSGPUTコマンドのマクロ値である「MSGPUT」を指定します。
DCOM
アプリケーションプログラムのAPI通信領域としてSYNC-DCOMを指定します。
-
SYNC-DCOM : 制御権がある通信の場合に指定します。
-
ASYNC-DCOM : 制御権がない通信に指定するため、使用してはなりません。
出力メッセージ領域
送信するデータが格納されているメッセージ領域名を指定します。
SPA
SYNC-DCOMを使用する場合、ワークステーションに送信するSPAデータ領域の名前を指定します。
-
SPA領域は省略可能です。
-
セッションの終了時、DCOMのSPALに-1を設定します。
-
3. SWITCH
SWITCHは、アプリケーションプログラム間の通信を行うコマンドです。アプリケーションプログラムの出力メッセージ領域の内容が他のアプリケーションプログラムの入力メッセージ領域に送信されます。
以下は、SWITCHコマンドの使用例です。
WORKING-STORAGE SECTION. 01 SYNC-DCOM. COPY COBSDCOM. 01 OUT-DATA. 02 FILLER PIC S9(5) COMP VALUE 128. 02 FILLER PIC S9(5) COMP VALUE 0. 02 DATA PIC X(128). COPY CBACSAPI. 01 ACSSPA PIC X(128). ... PROCEDURE DIVISION. MOVE 'APL001' TO NAME OF SYNC-DCOM. MOVE 24 TO MSGL OF SYNC-DCOM. MOVE SPACE TO OPTC OF SYNC-DCOM. CALL 'ACSAPI' USING SWITCH SYNC-DCOM OUT-DATA ACSSPA.
-
呼び出し形式
CALL 'ACSAPI' SWITCH, DCOM, 出力メッセージ領域[, ACSSPA].
-
パラメータ
以下は、SWITCHコマンドを使用する場合に設定するパラメータの説明です。
パラメータ 説明 SWITCH
SWITCHコマンドのマクロ値である「SWITCH」を指定します。
DCOM
アプリケーションプログラムのAPI通信領域としてSYNC-DCOMとASYNC-DCOMのいずれかを指定します。
-
SYNC-DCOM : 制御権がある通信の場合に指定します。
-
ASYNC-DCOM : 制御権がない通信の場合に指定します。
出力メッセージ領域
送信するデータが格納されているメッセージ領域名を指定します。
SPA
SYNC-DCOMを使用する場合、SPAデータを格納する領域の名前を指定します。
-
SYNC-DCOMの場合、SPA領域は省略可能です。
-
ASYNC-DCOMの場合、SPA領域を指定できません。
-
4. VGET
VGETは、アプリケーションプログラムでVSAMデータセット・レコードを入力するコマンドです。現在は、キー順データセット(KSDS)のみをサポートしています。
以下は、VGETコマンドの使用例です。
WORKING-STORAGE SECTION. 01 VCOM. COPY COBVCOM. 01 DD-NAME PIC X(8) VALUE 'VSAMDAT '. 01 INPUT-DATA. 02 IN-KEY. 02 IN-DATA PIC X(128). COPY CBACSAPI. ... PROCEDURE DIVISION. MOVE 'DIR' TO VOPTCD02. MOVE 'KEQ' TO VOPTCD05. MOVE 'FWD' TO VOPTCD09 . MOVE 200 TO VAREALEN. MOVE 9 TO VKEYLEN. CALL 'ACSAPI' USING VGET DD-NAME VCOM INPUT-DATA IN-KEY.
-
呼び出し形式
CALL 'ACSAPI' VGET, DD名, VCOM, 入力レコード名[, アクセスキー].
-
パラメータ
以下は、VGETコマンドを使用する場合に設定するパラメータの説明です。
パラメータ 説明 VGET
VGETコマンドのマクロ値である「VGET」を指定します。
DD名
アクセスするデータセット名を指定します。8バイトの文字列で、空白を含むことができます。
VCOM
VCOM通信領域(VSAM Communication Area)の名前を指定します。
入力レコード名
VSAMデータセットから読み込んだデータを格納する入力レコード領域の名前を指定します。
アクセスキー
アクセスキーが格納されている領域の名前を指定します。
5. VPUT
VPUTは、アプリケーションプログラムでVSAMデータセット・レコードを出力するコマンドです。
以下は、VPUTコマンドの使用例です。
WORKING-STORAGE SECTION. 01 VCOM. COPY COBVCOM. 01 DD-NAME PIC X(8) VALUE 'VSAMDAT '. 01 OUTPUT-DATA. 02 OUT-KEY. 02 OUT-DATA PIC X(128). COPY CBACSAPI. ... PROCEDURE DIVISION. CALL 'ACSAPI' USING VPUT DD-NAME VCOM OUTPUT-DATA OUT-KEY.
-
呼び出し形式
CALL 'ACSAPI' VPUT DD名, VCOM, 出力レコード名[, アクセスキー].
-
パラメータ
以下は、VPUTコマンドを使用する場合に設定するパラメータの説明です。
パラメータ 説明 VPUT
VPUTコマンドのマクロ値である「VPUT」を指定します。
DD名
アクセスするデータセット名を指定します。8バイトの文字列で、空白を含むことができます。
VCOM
VCOM通信領域(VSAM Communication Area)の名前を指定します。
出力レコード名
VSAMデータセットに保存する出力レコード領域の名前を指定します。
ACCESS-KEY
アクセスキーが格納されている領域名を指定します。
6. VPOINT
VPOINTコマンドは、レコードを順次処理する場合(VOPTCD02=SEQ)、処理の開始位置を事前に指定し、その位置から順にレコードを処理するために使用されます。ユーザーは、指定したキーに対して完全一致(VOPTCD06=FKS)または部分一致(VOPTCD06=GEN)の方式を選択できます。
以下は、VPOINTコマンドの使用例です。
WORKING-STORAGE SECTION. 01 VCOM. COPY COBVCOM. 01 DD-NAME PIC X(8) VALUE 'VSAMDAT '. 01 VSAM-DATA. 02 VSAM-KEY PIC X(8). 02 VSAM-DATA PIC X(72). COPY CBACSAPI. ... PROCEDURE DIVISION. CALL 'ACSAPI' USING VPOINT DD-NAME VCOM VSAM-KEY.
-
呼び出し形式
CALL 'ACSAPI' VPOINT DD名, VCOM, アクセスキー.
-
パラメータ
以下は、VPOINTコマンドを使用する場合に設定するパラメータの説明です。
パラメータ 説明 VPOINT
VPOINTコマンドのマクロ値である「VPOINT」を指定します。
DD名
アクセス対象のデータセット名を指定します。8バイトの文字列で、空白を含みます。
VCOM
VCOM(VSAM-Communication Area)の領域名を指定します。
ACCESS-KEY
アクセスキーが格納されている領域名を指定します。
7. VENDREQ
VENDREQコマンドは、VSAMの順次検索処理時に設定されたレコード位置を解除するために使用されます。VENDREQを指定すると、順次検索(VOPTCD02=SEQ)に対して現在のレコード位置の設定が解除され、初期位置にリセットされます。
以下は、VPUTコマンドの使用例です。
WORKING-STORAGE SECTION. 01 VCOM. COPY COBVCOM. 01 DD-NAME PIC X(8) VALUE 'VSAMDAT '. 01 OUTPUT-DATA. 02 OUT-KEY. 02 OUT-DATA PIC X(128). COPY CBACSAPI. ... PROCEDURE DIVISION. CALL 'ACSAPI' USING VENDREQ DD-NAME VCOM.
-
呼び出し形式
CALL 'ACSAPI' VENDREQ DD名, VCOM.
-
パラメータ
以下は、VENDREQコマンドを使用する場合に設定するパラメータの説明です。
パラメータ 説明 VENDREQ
コマンドのマクロ値である「VENDREQ」を指定します。
DD名
アクセス対象のデータセット名を指定します。8バイトの文字列で、空白を含みます。
VCOM
VCOM(VSAM-Communication Area)の領域名を指定します。
8. DSREAD
DSREADは、アプリケーションプログラムでBDAMデータセット・レコードを入力するコマンドです。
以下は、DSREADコマンドの使用例です。
WORKING-STORAGE SECTION. 01 DD-NAME PIC X(8) VALUE 'BDAMDAT '. 01 IN-DATA. 02 DATA-F PIC X(128). 01 DD-ADDR PIC 9(8) COMP. COPY CBACSAPI. ... PROCEDURE DIVISION. CALL 'ACSAPI' USING DSREAD DD-NAME IN-DATA DD-ADDR.
-
呼び出し形式
CALL 'ACSAPI' DSREAD, DD-NAME, 入力データ領域名, RBN.
-
パラメータ
以下は、DSREADコマンドを使用する場合に設定するパラメータの説明です。
パラメータ 説明 DSREAD
DSREADコマンドのマクロ値である「DSREAD」を指定します。
DD-NAME
処理するBDAMデータセットの名前を指定します。
入力データ領域名
BDSMデータセットから読み込んだデータを格納する入力データ領域の名前を指定します。
RBN
RBN(Related Block Number)の値を指定します。
9. DSWRITE
DSWRITEは、アプリケーションプログラムでBDAMデータセット・レコードを出力するコマンドです。
以下は、DSWRITEコマンドの使用例です。
WORKING-STORAGE SECTION. 01 DD-NAME PIC X(8) VALUE 'BDAMDAT '. 01 OUT-DATA. 02 DATA-F PIC X(128). 01 DD-ADDR PIC 9(8) COMP. COPY CBACSAPI. ... PROCEDURE DIVISION. CALL 'ACSAPI' USING DSWRITE DD-NAME OUT-DATA DD-ADDR.
-
呼び出し形式
CALL 'ACSAPI' DSWRITE, DD-NAME, 出力データ領域名, RBN.
-
パラメータ
以下は、DSWRITEコマンドを使用する場合に設定するパラメータの説明です。
パラメータ 説明 DSWRITE
DSWRITEコマンドのマクロ値である「DSWRITE」を指定します。
DD-NAME
処理するBDAMデータセットの名前を指定します。
出力データ領域名
BDAMデータセットに保存する出力データ領域の名前を指定します。
RBN
RBN(Related Block Number)値を指定します。
10. URGPUT
URGPUTは、ワークステーションに緊急メッセージを出力するコマンドです。アプリケーションプログラムの出力メッセージ領域の内容がワークステーションに送信されます。
以下は、URGPUTコマンドの使用例です。
WORKING-STORAGE SECTION. 01 ASYNC-DCOM. COPY COBSDCOM. 01 OUT-DATA. 02 PUT-MSG PIC X(128). COPY CBACSAPI. ... PROCEDURE DIVISION. MOVE SPACE TO OPTC OF ASYNC-DCOM. MOVE 'FMT001' TO FMID OF ASYNC-DCOM. MOVE 'WS0001' TO NAME OF ASYNC-DCOM. CALL 'ACSAPI' USING URGPUT ASYNC-DCOM PUT-MSG.
-
呼び出し形式
CALL 'ACSAPI' URGPUT, DCOM, 出力メッセージ領域名.
-
パラメータ
以下は、URGPUTコマンドを使用する場合に設定するパラメータの説明です。
パラメータ 説明 URGPUT
URGPUTコマンドのマクロ値である「URGPUT」を指定します。
DCOM
アプリケーションプログラムのAPI通信領域としてASYNC-DCOMを指定します。SYNC-DCOMは使用できません。
出力メッセージ領域名
緊急メッセージが保存されている出力メッセージ領域の名前を指定します。
11. ACSEXT
ACSEXT(またはXTRNAL)は、他のACSまたはAIMシステムのアプリケーションプログラムにメッセージを送信するためのコマンドです。
以下は、ACSEXTコマンドの使用例です。
WORKING-STORAGE SECTION. 01 ASYNC-DCOM. COPY COBSDCOM. 01 OUT-DATA. 02 FILLER PIC S9(5) COMP VALUE 128. 02 FILLER PIC S9(5) COMP VALUE 0. 02 DATA PIC X(128). COPY CBACSAPI. ... PROCEDURE DIVISION. MOVE SPACE TO NAME OF ASYNC-DCOM. MOVE 'APL001' TO SNAME OF ASYNC-DCOM. MOVE 128 TO MSGL OF ASYNC-DCOM. MOVE SPACE TO OPTC OF ASYNC-DCOM. CALL 'ACSAPI' USING ACSEXT ASYNC-DCOM OUT-DATA.
-
呼び出し形式
CALL 'ACSAPI' ACSEXT(またはXTRNAL), DCOM, 出力メッセージ.
-
パラメータ
以下は、ACSEXT(またはXTRNAL)コマンドを使用する場合に設定するパラメータの説明です。
パラメータ 説明 ACSEXT (またはXTRNAL)
ACSEXTコマンドのマクロ値である「ACSEXT」、またはXTRNALコマンドのマクロ値である「XTRNAL」を指定します。
DCOM
アプリケーションプログラムのAPI通信領域としてASYNC-DCOMを指定します。SYNC-DCOMは使用できません。
出力メッセージ
他のシステムに送信するメッセージが保存されている出力メッセージ領域の名前を指定します。
12. ACSNOTE
ACSNOTEコマンドは、アプリケーションプログラムの異常終了出口ルーチンで使用されます。異常出口ルーチンは、異常の原因を分析するための情報を通知します。
以下は、ACSNOTEコマンドの使用例です。
WORKING-STORAGE SECTION. 01 ABEND-DATA. 02 APLNAME PIC X(8). 02 FILLER PIC X(4). 02 ABEND-LIMIT PIC 9(02) COMP. 02 ABEND-COUNT PIC 9(02) COMP. COPY CBACSAPI. ... PROCEDURE DIVISION. CALL 'ACSAPI' USING ACSNOTE ABEND-DATA.
-
呼び出し形式
CALL 'ACSAPI' ACSNOTE, ABENDの通知領域.
-
パラメータ
以下は、ACSNOTEコマンドを使用する場合に設定するパラメータの説明です。
パラメータ 説明 ACSNOTE
ACSNOTEコマンドのマクロ値である「ACSNOTE」を指定します。
ABENDの通知領域
ACS情報の通知領域を指定します。通知領域にはアプリケーションプログラム名、ABEND LIMIT値、ABEND回数が含まれます。
13. APABEND
APABENDは、アプリケーションプログラムを異常終了するコマンドです。
以下は、APABNEDコマンドの使用例です。
WORKING-STORAGE SECTION. COPY CBACSAPI. ... PROCEDURE DIVISION. CALL 'ACSAPI' USING APABEND.
-
呼び出し形式
CALL 'ACSAPI' APABEND.
-
パラメータ
以下は、APABENDコマンドを使用する場合に設定するパラメータの説明です。
パラメータ 説明 APABEND
APABENDコマンドのマクロ値である「APABEND」を指定します。
14. VCOM
アプリケーションプログラムでVSAMに対するACS APIを使用するには、通信領域であるVCOM(VSAM Communication)領域を指定する必要があります。
以下は、VCOMに対する定義です。
01 VCOM-AREA.
03 VOPTCD.
05 VOPTCD01 PIC X(4) VALUE IS 'KEY '.
05 VOPTCD02 PIC X(4) VALUE IS 'SEQ '.
05 VOPTCD03 PIC X(4) VALUE IS 'SYN '.
05 VOPTCD04 PIC X(4) VALUE IS 'NUP '.
05 VOPTCD05 PIC X(4) VALUE IS 'KEQ '.
05 VOPTCD06 PIC X(4) VALUE IS 'FKS '.
05 VOPTCD07 PIC X(4) VALUE IS 'MVE '.
05 VOPTCD08 PIC X(4) VALUE IS 'ARD '.
05 VOPTCD09 PIC X(4) VALUE IS 'FWD '.
05 VOPTCD10 PIC X(4) VALUE IS 'NWA '.
03 VRTNCD.
05 VMJR PIC X(2) VALUE IS '00'.
05 VMNR PIC X(2) VALUE IS '00'.
03 VACB PIC 9(8) COMP VALUE IS 0.
03 VAIXPC PIC 9(8) COMP VALUE IS 0.
03 VAREA PIC 9(8) COMP VALUE IS 0.
03 VAREALEN PIC 9(8) COMP VALUE IS 0.
03 VARG PIC 9(8) COMP VALUE IS 0.
03 VECB PIC 9(8) COMP VALUE IS 0.
03 VFDBK.
05 VFDBK1 PIC 9(4) COMP VALUE IS 0.
05 VFDBK2 PIC 9(4) COMP VALUE IS 0.
03 VFTNCD PIC 9(8) COMP VALUE IS 0.
03 VKEYLEN PIC 9(8) COMP VALUE IS 0.
03 VMSGAREA PIC 9(8) COMP VALUE IS 0.
03 VMSGLEN PIC 9(8) COMP VALUE IS 0.
03 VNXTRPL PIC 9(8) COMP VALUE IS 0.
03 VRBA PIC 9(8) COMP VALUE IS 0.
03 VRECLEN PIC 9(8) COMP VALUE IS 0.
03 VTRANSID PIC 9(8) COMP VALUE IS 0.
03 VRSV.
05 VRSV1 PIC 9(8) COMP VALUE IS 0.
05 VRSV2 PIC 9(8) COMP VALUE IS 0.
05 VRSV3 PIC 9(8) COMP VALUE IS 0.
05 VRSV4 PIC 9(8) COMP VALUE IS 0.
05 VRSV5 PIC 9(8) COMP VALUE IS 0.
05 VRSV6 PIC 9(8) COMP VALUE IS 0.
-
パラメータ
以下は、VCOM領域の各項目の説明です。
パラメータ 説明 VOPTCD
アプリケーションプログラムがVSAMデータセットに対して処理する方法を指定します。
VTRNCD
レコードの入出力要求に対するリターンコードです。(現在はサポートされていません)
VAREALEN
アプリケーションプログラムの入出力レコード領域の長さを指定します。
VFDBK
レコードの入出力要求に対するVSAMリターンコードです。
VFTNCD
物理エラーが発生した際の機能コードです。(現在はサポートされていません)
VKEYLEN
キー値を指定する場合、そのキーの長さを指定します。
VRBA
最後に処理されたRBAが返されます。(現在はサポートされていません)
VRECLEN
レコード入出力時のデータレコード長を指定します。(現在はサポートされていません)
ACSAPIのVCOMで使用されるVOPTCDの値と意味は以下のとおりです。
-
VOPTCD
以下は、VOPTCDの各項目の説明です。
パラメータ 値 説明 VOPTCD01
ADR
KSDSまたはESDSに対し、アドレス値を基準にレコードにアクセスします。
VOPTCD01
KEY
KSDSまたはRRDSに対し、RRNまたは指定したキー値を基準にレコードにアクセスします。(デフォルト値)
VOPTCD02
DIR
KSDS、ESDSまたはRRDSに対し、直接アクセスを行います。
VOPTCD02
SEQ
KSDS、ESDSまたはRRDSに対し、順次アクセスを行います。(デフォルト値)
VOPTCD02
SKP
現在サポートされていません。
VOPTCD03
SYN
VSAM要求の実行が完了すると、ユーザープログラムに戻ります。
VOPTCD04
NSP
VSAMは順次処理を継続するためにレコードの位置を記憶します。(現在サポートされていません)
VOPTCD04
NUP
検索レコードは更新および削除対象ではありません。(現在サポートされていません)
VOPTCD04
UPD
検索レコードは更新および削除対象です。(デフォルト値)
VOPTCD05
KEQ
指定したキー値と完全または部分一致するレコードを検索します。(デフォルト値)
VOPTCD05
KGE
指定したキー値と完全または部分一致するか、またはそれより大きいキー値のレコードを検索します。
VOPTCD06
FKS
VGETまたはVPOINTの処理時、指定したキーをレコードのキー値として処理します。(デフォルト値)
VOPTCD06
GEN
VGETまたはVPOINTの処理時、指定したキーをレコードの一部として処理します。
VOPTCD07
MVE
現在サポートされていません。
VOPTCD08
ARD
現在サポートされていません。
VOPTCD08
LRD
現在サポートされていません。
VOPTCD09
FWD
データを前方に移動し、順次処理方式で検索します。(デフォルト値)
VOPTCD09
BWD
データを後方に移動し、順次処理方式で検索します。
VOPTCD10
NWA
現在サポートされていません。
FDBKは、VSAMへのアクセス処理に対する結果を示します。
-
FDBK
以下は、FDBKの値の説明です。
VFDBK1 VFDBK2 説明 0
0
レコードの処理が正常に行われました。
0
4
重複するキーを持つレコードに対する処理が行われました。
8
4
順次アクセス時にファイルの最後のレコードに到達したか、VTOPCD05にKGEが指定されている状態で検索対象のレコードが存在しない場合に発生します。
8
8
同一キーを持つレコードがすでに存在します。
8
16
VOPTCD05にKEQを指定して特定のキー値に該当するレコードの位置を指定したが、そのキーを持つレコードが見つからなかった場合です。
12
4
データセットの読み込み中にエラーが発生しました。
12
16
データセットへの書き込み中にエラーが発生しました。