~APPC通信プログラムの作成~
IBM i のSNA通信 (APPCプログラミング編)

１）ICFファイルの作成

APPC通信プログラムを作成するには、起動側、受動側のそれぞれで、送受信するデータのフォーマット（レコード様式）の定義と、会話制御用のDDSキーワードを含むICFファイルを作成します。必ずしもフォーマットを一致させる必要はありませんが、一般的に送受信するデータのフォーマットは共通ですので、起動側、受動側で同じものを作成します。作成するICFファイルの名前は、同じでも異なっていても構いません。


この例では、起動側、受動側のAPPC通信プログラム用に、それぞれICFファイル「APPCICF」を作成します。DDSは同じもので、送受信するフォーマットを共通にします。

・遠隔プログラムの起動に関するキーワード（レコード様式「EVKREC」）
遠隔プログラムの起動用のレコード様式には、「EVOKE」と「SECURITY」キーワードを指定します。APPCの特徴でもある同期会話を行いたいときは、「SYNLVL(*CONFIRM)」キーワードも併せて指定します。これらのキーワードには、条件付けの標識は使えません。受動側プログラムは、この遠隔プログラム開始要求を受けて起動されますので、起動用のレコード様式は、起動側のプログラムでのみ使用します。受動側のプログラムから改めてAPPC同期会話を要求することはできません。
EVOKEキーワードには、ライブラリ名/プログラム名と、遠隔プログラム起動時に渡されるパラメータをオプションで指定します。相手プログラムやライブラリー名が固定の時は、固定情報（リテラル）でも指定できますが、一般的には「プログラム・システム間フィールド」を指定します。プログラム・システム間フィールドは、通信相手に送信される値を指定するのではなく、書き出すプログラム側が、システムの管理機能に渡したい情報を指定するフィールドです。プログラム・システム間フィールドは、使用するレコード様式内に、38桁目の使用目的を「P」として定義してあげます。遠隔プログラムの起動時に渡されるパラメータにも、プログラム・システム間フィールドを使用することができます。
システム提供のAPPC通信プログラムの場合、IBM i の実行管理機能で省略時のユーザーが割り当てられますが、ユーザー作成のAPPC遠隔プログラムの起動時には、遠隔システムに対してセキュリティ情報（ユーザー名、パスワード）を送ってあげる必要があります。それを指定するのが「SECURITY」キーワードで、オプション2が「パスワード」、オプション3が「ユーザー・プロファイル名」になります。

・APPC会話の終了（切り離し）に関するキーワード（レコード様式「DETACH」）
APPC会話の終了（切り離し）は、「DETACH」キーワードを含むレコード様式を出力することで行います。APPC会話の終了は、起動側、受動側のどちらからでも行うことができます。切り離し要求が出力されると、それまで送信用のバッファに溜まっていた送信データがあれば、それらが全て相手プログラムに送信され、それに続いて切り離し要求フラグが相手に送られます。バッファにデータが無い時は、切り離し要求フラグのみが送信されます。送られた切り離し要求フラグは、送信されたデータがあればその最後の送信データブロックと共に、送信データが無ければ切り離し要求フラグが単独で相手プログラムに受信されます。切り離しが成功した後は、起動側プログラムの場合、獲得済みのAPPC通信セッションを解放して終了するか、あるいはそのAPPC通信セッションを通して同じ遠隔ロケーションで、別の遠隔プログラムを開始することができます。受動側のプログラムは、獲得している「遠隔ロケーション名=*REQUESTER」のAPPC通信セッションを解放して終了します。
同期会話が有効なAPPC会話の場合、切り離しと一緒に確認を要求することもできます。確認要求付きで切り離しを送った場合、送った側のプログラムの実行は抑止（ブロック）され、相手からの応答を待ちます。確認を要求された側は、肯定応答/否定応答のいずれかを送って、切り離し要求に応答します。この時にデータを一緒に送信することはできません。（相手は送信状態で実行が抑止されているので、データを送っても受信されません。）肯定応答で応えた時は切り離しは成功してAPPC会話が終了し、否定応答で応答した時は、切り離しは失敗してAPPC会話は終了しません。切り離しの要求に対して否定応答を送った側が、次のデータや理由を送信する責任がありますので、否定された切り離し要求を送った側は、それらを受信する責任があります。

・同期会話に関するキーワード
APPC同期会話を行うには、前にも記述しましたが、遠隔プログラム開始要求の「EVOKE」キーワードと一緒に「SYNLVL(*CONFORM)」を記述して、遠隔プログラムを開始しなければなりません。これで開始されたAPPC会話では、同期会話を行うことができるようになり、データ送信時に「CONFIRM」キーワードを有効にすることで、強制的にデータを相手に送るとともに、相手に確認を要求することができます。APPC会話の相手プログラムは、この送信データ（データが複数ブロックの場合は、最後のデータ）と一緒に相手の確認要求を受け取ります。（「RCVCONFIRM」キーワードの応答標識がON）確認要求を受け取った側は、相手に対して肯定応答（「RSPCONFIRM」キーワード）、または否定応答（「FAIL」キーワード）のみの応答を送信します。この時、確認を要求した相手はデータ送信状態で実行がブロックされて停止している訳ですから、応答を送る側は、肯定/否定応答以外のデータを送ることはできません。
確認を要求した側は、相手が肯定応答（「RSPCONFIRM」キーワード）を返してきた場合は、確認要求付きのデータ送信が正常に完了しますが、相手が肯定応答以外（例えば「FAIL」キーワード）を返してきた場合、確認要求付きのデータ送信は例外エラーで終了し、データ送信状態も解除されてしまいますので、データ送信例外エラーのハンドリングをした後で、否定応答の理由などのデータを受信しなければなりません。

・受信に関するキーワード
受信に関するキーワードは、プログラムがデータ受信状態にあるときに、データと一緒に、または単独で送信側からの状態通知を受け取って、指定されている応答標識をオンにしてくれるキーワードです。レコード・レベルでも指定できますが、一般的にはファイル・レベルで指定して、すべてのレコード様式での受信操作時に有効になるようにします。

a.RCVDETACHキーワード
送信側が切り離し要求（「DETACH」キーワード）を送信してきたことを受信側プログラムに通知します。

b.RCVTRNRNDキーワード
送信側が、ALWWRTキーワード、またはINVITEキーワードを送信して、明示的に送信権を譲渡することを通知してきたか、あるいは送信側が送信状態から受信状態に転じて送信権を放棄したことを、受信側プログラムに通知します。

c.RCVCONFIRMキーワード
送信側が、CONFIRMキーワードを有効にしてデータを送信し、確認を要求していることを、受信側プログラムに通知します。これに対して受信側プログラムは、RSPCONFIRMキーワードを使用して肯定応答を行うか、FAILキーワードを使用して、否定応答を受け取り、送信権を受信側のプログラムに移します。

d.RCVFAILキーワード
送信側がFAILキーワードを有効にして送信してきたことを受信側プログラムに通知します。確認要求に対する否定応答にもFAILキーワードを使用しますが、この場合、RCVFAILキーワードの応答標識はONになりません。

・送信に関するその他のキーワード
送信に関するキーワードは、送信側がデータと併せて、またはデータ無しの単独で使用するキーワードです。

a.書き出し許可「ALWWRT」キーワード
送信権を持っている側が、受信状態の相手に対して送信権を明示的に譲渡することを指定します。

b.送信勧誘「INVITE」キーワード
相手にデータ送信を勧誘します。ALWWRTキーワードとの違いは、1)送信権があっても無くても送信することができる、2)送信勧誘後、一定時間データ受信を待機して、受信が無ければ送信勧誘をキャンセルすることができる、3)複数の通信相手（遠隔ロケーション）に対してデータの送信を勧誘できる、などがあります。

c.レコード様式名通知「FMTNAME」キーワード
相手に、送信に使用したレコード様式名を通知し、受信レコード様式選択機能を使用してデータの受信を可能にするときに、送信側プログラムで使用します。ADDICFDEVEコマンドで、FMTSLT(*RMTFMT)キーワードの指定が必要です。

d.受診データ内の文字値によるデータ受信「RECID」キーワード
受信側プログラムが、受信データ内の特定位置の文字値によって、データを受信するレコード様式を選択する時に使用します。ADDICFDEVEコマンドで、FMTSLT(*RECID)キーワードの指定が必要です。

FMT *    *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 ...+
0001.00  *** テスト用 ICFF                                        
0002.00 A                                      RCVDETACH(39)      
0003.00 A                                      RCVTRNRND(40)      
0004.00 A                                      RCVCONFIRM(38)      
0005.00 A                                      INDARA              
0006.00  *** プログラム起動用                                      
0007.00 A          R EVKREC                    EVOKE(&X1LIB/&X1PGM +
0008.00 A                                            &X1PRDLIB)    
0009.00 A                                      SECURITY(2 &X1PASS +
0010.00 A                                               3 &X1USER)
0011.00 A                                      SYNLVL(*CONFIRM)    
0012.00                                                            
0013.00 A            X1USER        10A  P                          
0014.00 A            X1PASS        10A  P                          
0015.00 A            X1PGM         10A  P                          
0016.00 A            X1LIB         10A  P            
0017.00                                              
0018.00 A            X1PRDLIB      10A  P            
0019.00  *** 送受信用                                
0020.00 A          R SNDRCV                          
0021.00 A  56                                  CONFIRM
0022.00 A  31                                  FRCDTA
0023.00 A  32                                  ALWWRT
0024.00 A            X1DATA      4000O              
0025.00                                              
0026.00 A            X1JOBNAM      10A              
0027.00 A            X1JOBUSR      10A              
0028.00 A            X1JOBNBR       6A              
0029.00 A            X1JOBID       16A              
0030.00  *** 切り離し用                              
0031.00 A          R DETACH                    DETACH
0032.00 A  56                                  CONFIRM  
0033.00  *** 肯定応答                                    
0034.00 A          R RSPCONF                   RSPCONFIRM
0035.00  *** 否定応答                                    
0036.00 A          R RSPFAIL                   FAIL      

・ICFファイルの作成と、プログラム装置項目の追加
ICFファイル用のDDSの入力が終了したら、ICFファイルを作成（コンパイル）します。

CRTICFF FILE(*CURLIB/ICFFILE) ACQPGMDEV(*NONE) MAXPGMDEV(1) WAITRCD(*NOMAX)

a.ACQPGMDEVパラメータ
作成したICFファイルを使用するプログラムが、ICFファイルをオープンする時に、自動的に獲得されるプログラム装置名を指定します。明示的に「ACQ」命令でプログラム装置（=通信したい遠隔ロケーション）を獲得する時、あるいは複数のプログラム装置を使用する時は「*NONE」のままとします。

b.MAXPGMDEVパラメータ
このICFファイルに追加するプログラム装置の最大数を指定します。プログラム装置=通信したい遠隔ロケーション=通信相手プログラムですから、１つのAPPC通信プログラムで、複数の遠隔ロケーション、または複数の相手プログラムと会話を行いたいときに変更します。省略値は1、最大値は256です。

c.WAITRCDパラメータ
相手プログラムに対して送信勧誘を行って、受信待機する時間を指定したいときに使用します。省略値は*NOMAX（無制限）で、使用する時は秒数を指定します。


ICFファイルの作成終了後、APPC通信プログラムで使用するプログラム装置項目を追加します。ICFファイル再作成後は、プログラム装置項目も置き換えられてなくなっていますので、再度追加します。

a.起動側のAPPC通信プログラム用のプログラム装置項目

ADDICFDEVE FILE(*LIBL/ICFFILE) PGMDEV(SOURCE) RMTLOCNAME(TARGET) CMNTYPE(*APPC) FMTSLT(*PGM) CNVTYPE(*SYS)

a.PGMDEVパラメータ
プログラム内で使用する、プログラム装置名を指定します。

b.RMTLOCNAMEパラメータ
通信相手の遠隔ロケーション名を指定します。

c.FMTSLT(*PGM)、CNVTYPE(*SYS)パラメータ
レコード様式選択機能として、FMTNAMEキーワード、RECIDキーワードを使用する時に、FMTSLTパラメータを使用します。レコード様式名での受信操作を行うときは、FMTSLT(*PGM)を指定します。CNVTYPE(*SYS)は、APPCマップ式会話を示します。ICFファイルを使用したAPPC通信では、一般的にCNVTYPE(*SYS)を使用します。

b.受動側ｎAPPC通信プログラム用のプログラム装置項目

ADDICFDEVE FILE(*LIBL/ICFFILE) PGMDEV(TARGET) RMTLOCNAME(*REQUESTER) CMNTYPE(*APPC) FMTSLT(*PGM) CNVTYPE(*SYS)

PGMDEVパラメータは、プログラムで使用するプログラム装置名を指定します。RMTLOCNAMEパラメータには、予約語「*REQUESTER」を指定して、起動側プログラムが遠隔プログラム開始要求を出してきたAPPC通信セッションを獲得することを示します。FMTSLTパラメータ、CNVTYPEパラメータは、起動側のプログラム装置項目に一致させます。

２）RPGLE APPC通信プログラムの作成

ICFファイルを作成したら、起動側、受動側でそれぞれAPPC通信プログラムを作成します。プログラムの作成には、メッセージ・フロー（データの送信順序）が重要ですので、あらかじめ双方で取り決めておきます。起動側のプログラムが開始され、受動側のプログラムを起動してAPPC会話が成立した時点では、データ送信をする側は起動側になります。起動側プログラムから遠隔プログラム開始要求で開始された受動側プログラムの第一オペレーションは「受信」操作になります。起動側プログラムが何も送信せずにいきなり受信に転じた場合、受動側プログラムは第一オペレーションで「送受反転」（RCVTRNRNDキーワードの応答標識ON）を受け取りますので、受動側プログラムが送信する側になります。あとは、メッセージ・フローに従った送受信操作を行います。
IBM i で、起動側から遠隔プログラム開始要求を受けて開始される受動側プログラムは、通信サブシステム（QCMN、またはQBASE）内の通信ジョブで、経路指定プログラムとして開始されます。通信ジョブ用のジョブ記述は、省略値として「*USRPRF」となっていますので、遠隔プログラム開始要求で送られてきたユーザー・プロファイルにジョブ記述が指定されていて、ジョブ記述内にライブラリー・リスト等のジョブ初期設定情報が記述されていた場合は、受動側でRPGLEプログラムを直接呼び出すこともできますが、一般的には、ジョブのライブラリー・リストなどの設定を行うCLプログラムなどを呼び出して、CLプログラムからCALLコマンドでRPGLEプログラムを呼び出すようにします。

・ファイル仕様書
ファイル仕様書でICFファイルを定義する時に必要なキーワードは、DEVIDキーワードとMAXDEVキーワードになります。DEVIDキーワードには、送信・受信操作を行うプログラム装置名を入れる変数を指定します。MAXDEVキーワードは、このファイルが複数装置ファイルであることを定義するとともに、プログラム装置の最大数を指定します。一般的にはICFファイルに定義されたプログラム装置数をそのまま使用しますので、MAXDEV(*FILE)を指定します。
ICFファイルを取り扱うときは、ファイルの入出力フィードバック域情報が必要になりますので、INFDSキーワードを使用して、ファイル情報データ構造を指定します。ファイル情報データ構造には、最後に操作したレコード様式名、プログラム装置名と、入出力操作毎に更新されるメジャー・マイナー戻りコードが含まれています。
ICFファイルの入出力操作で、応答標識や条件付けの標識に対して独立標識域（01～99）を使用する時は、INDDSキーワードを使用します。これによって数字標識（01～99）に名前を付けることができて、より判りやすくなります。

FMT *    *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 .
0004.00 FAPPCICF   CF   E             WORKSTN USROPN            
0005.00 F                                     INFDS(D#INFDS)    
0006.00 F                                     INDDS(D#INDICATORS)
0007.00 F                                     DEVID(F#PGMDEV)  
0008.00 F                                     MAXDEV(*FILE)    

・定義仕様書
定義仕様書では、ファイル情報データ構造（この例ではD#INFDS）、独立標識域用データ構造（この例ではD#INDICATORS）、
および操作するプログラム装置名用の変数を定義します。

FMT *    *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 .
0013.00  *** プログラム状況                
0014.00 D                SDS                
0015.00 D  S#PROG                 1     10  
0016.00 D  S#WSID               244    253  
0017.00 D  S#USER               254    263  
0018.00 D  S#JNBR               264    269  
0019.00  *** ファイル情報                  
0020.00 D  D#INFDS        DS                
0021.00 D    W#RCDFMT           261    270A
0022.00 D    W#PGMDEV           273    282A
0023.00 D    W#LC               370    371B 0
0024.00 D    W#TOP              378    379B 0
0025.00 D    W#MAJOR            401    402A
0026.00 D    W#MINOR            403    404A
0027.00  *** 標識                          
0028.00 D  D#INDICATORS   DS                
0029.00 D    I#FLASH             31     31N
0030.00 D    I#ALWWRT            32     32N
0031.00 D    I#RCVCONF           38     38N
0032.00 D    I#RCVDET            39     39N
0033.00 D    I#TRNRND            40     40N
0034.00 D    I#CONFIRM           56     56N

0041.00 D  F#PGMDEV       S             10A

・演算仕様書

a.ACQ命令
ICFファイル作成で「ACQPGMDEV(*NONE)」とした場合や、２つ以上のプログラム装置項目を使用する場合は、起動側、受動側プログラム共に通信に先だってACQ演算命令でプログラム装置を獲得します。起動側プログラムは、通信したい遠隔ロケーションが明示指定されているプログラム装置を獲得し、受動側プログラムは、遠隔ロケーション名として「*REQUESTER」が指定されているプログラム装置を獲得します。起動側、受動側の両方で獲得が成功すると、APPC会話が開始されます。

b.REL命令
RPGLEプログラムで獲得したプログラム装置を解放します。解放の前に、切り離しを使用してAPPC会話を終了させておく必要があります。

c.WRITE命令
データの送信、データとAPPC会話制御情報、まだはデータ無しでAPPC会話制御情報のみの送信を行うときに使用します。WRITE命令に先だって、どのプログラム装置に対しての操作なのかを、プログラム装置名フィールドに設定する必要があります。WRITE命令はレコード様式に対して行います。送信バッファ内のデータを強制的に送信するキーワード（FRCDTA、ALWWRT、CONFIRM、DETACHなど）を含むレコード様式を、WRITE命令で送信した場合、送信バッファはフラッシュされて、相手にデータ/制御情報が送信されます。以外の時は、送信データは送信バッファに蓄えられて、バッファが一杯になるか、送信状態だったプログラムが受信状態に反転するか、バッファ内のデータを強制送信するキーワードが有効な状態でのWRIT命令作で送信されます。
APPC会話制御情報として、有効な確認要求（CONFIRMキーワード）を含むレコード様式を送信した場合、RPGLEプログラムは、相手からの確認応答/否定応答が返ってくるまで、実行がブロックされて停止します。確認要求に対して否定応答が返された場合は、WRITE命令は例外エラーで終了しますので、(E)オプションを付けて、エラー監視を行う必要があります。

d.READ命令
受診バッファから、データおよびAPPC会話制御情報を読み取るために、READ命令を使用します。ADDICFDEVEコマンドで、FMTSLT(*PGM)としたプログラム装置からの読み取りは、レコード様式名を指定したREAD命令を使用します。INVITEキーワードを使用して送信勧誘をしたプログラム装置からの読み取り、ADDICFDEVEコマンドでFMTSLT(*RECID)やFMTSLT(*RMTFMT)を指定して、レコード様式選択機能を使用した読み取りを行うときは、ICFファイル名を指定したREAD命令を使用します。送信勧誘を行ったプログラム装置からの読み取りについては、プログラム装置名フィールドをブランクにしますが、それ以外の読み取り操作では、READ命令に先だって、どのプログラム装置から読み取るかをプログラム装置名フィールドに設定します。

FMT *    *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 .
0068.00 C                   EVAL      F#PGMDEV      = 'SOURCE'
0069.00 C     F#PGMDEV      ACQ(E)    APPCICF                
0070.00 C                   IF        %ERROR                
0071.00 C                   EVAL      W#CTL         = 'END'  
0072.00 C                   LEAVESR                          
0073.00 C                   ENDIF                            

FMT *    *. 1 ...+... 2 ...+... 3 ...+... 4 ...+... 5 ...+... 6 .
0133.00 C                   WRITE     DETACH
0134.00 C     F#PGMDEV      REL(E)    APPCICF