KZAAPI
KZAAPIは、COBOLアプリケーション(ユーザー・プログラム)でDTSを使用するためのインターフェースです。OpenFrameでは、DTSの一部サービスであるSNDFILEとRCVFILE機能をサポートしており、FTPプロトコルを使用してファイルの送受信を提供します。本付録では、KZAAPIを使用するために作成する呼び出し形式とパラメータについて説明します。
-
呼び出し形式
CALL "KZAAPI" USING P-intlvl P-reqcode P-rc P-service P-parm1 P-parm2 ... P-parm.
-
パラメータ
以下は、KZAAPIのパラメータについての説明です。
-
P-intlvl
インターフェース・レベルを指定します。インターフェース・レベルは「C'11'」を指定しますが、OPNDTSとCLSDTSの場合は「C'20'」が使用されます。OpenFrameでは、SNDFILEとRCVFILEのみをサポートするため、「C'11'」を指定します。
-
P-reqcode
要求コードを指定します。
要求名 コード 備考 OPNDTS
C'21'
OpenFrameではサポートされていません。
CLSDTS
C'22'
OpenFrameではサポートされていません。
SNDFILE
C'01'
RCVFILE
C'02'
GETINF
C'12'
OpenFrameではサポートされていません。
FTRNRSP
C'06'
OpenFrameではサポートされていません。
TRANCOMP
C'14'
OpenFrameではサポートされていません。
CANCEL
C'05'
OpenFrameではサポートされていません。
INQUIRE
C'07'
OpenFrameではサポートされていません。
VARY
C'08'
OpenFrameではサポートされていません。
SNDMSG, SNDMSG(NODE)
C'18'
OpenFrameではサポートされていません。
MSGRSP
C'19'
OpenFrameではサポートされていません。
EXECUTE, EXECUTE(NODE)
C'20'
OpenFrameではサポートされていません。
-
P-rc
処理結果と完了結果を指定します。2バイトのエラー分類コード、2バイトのエラーコード、4バイトの詳細コード、8バイトの予備で構成されます。
-
P-Service
各サービス要求のパラメータを指定します。パラメータは可変であり、最後のパラメータはC’FF’値です。各パラメータは、識別子(最初の2バイト)と値で構成されます。OpenFrameはSNDFILEとRCVFILEのみをサポートしています。
以下は、SNDFILEの説明です。
区分 パラメータ コード 説明 共通
要求識別子
C'90'
ユーザーが任意の値を指定します。この値はファイル転送の完了通知に含まれ、ファイル転送要求などを確認するときに使用されます。
要求値
C'91'
要求形式は以下のとおりです。
-
0: 空白値(省略値)
-
1:完了戻り値
OpenFrameではサポートされていません。
アプリケーション名
C'92'
SNDFILEサービスを要求したアプリケーション名を左詰めで指定し、残りは空白で埋めます。
アプリケーションの動作環境
C'26'
要求形式が空白値の場合、ファイル転送の完了通知先のアプリケーションの動作環境を以下の形式で指定します。
-
1:TSS環境で動作するユーザープログラム
-
2:バッチ環境で動作するアプリケーション(省略値)
OpenFrameではサポートされていません。
完了通知先のアプリケーション名
C'25'
要求形式が空白値の場合、ファイル転送の完了通知先のアプリケーション名を左詰めで指定し、残りは空白で埋めます。このパラメータを省略した場合は、SNDFILEサービスを要求したユーザープログラムにファイル転送の完了を通知します。
OpenFrameでは省略した場合の動作が適用されます。リモート・ノード名
C'01'
リモート・ノード名を左詰めで指定し、残りは空白で埋めます。
関連付け
C'02'
ファイル転送サービスが完了したとき、関連付け(association)を維持するかどうかを指定します。
-
1:切断する
-
2:維持する(省略値)
OpenFrameでは指定の有無に関係なく、転送サービスが完了したときに関連付けを切断します。
ローカル
ファイル名
C'03'
ファイル名を左詰めで指定し、残りは空白で埋めます。
メンバー名
C'04'
区分編成ファイルの場合、メンバー名を左詰めで指定し、残りは空白で埋めます。
ファイルの割り当て
C'05'
他のジョブと共有できるようにファイルを割り当てるかどうかを指定します。
-
0 : 共有するために割り当てる(省略値)
-
1 : 排他的に割り当てる
デバイスグループ名
C'16'
ファイルがカタログされていない場合は、デバイスグループ名を左詰めで指定し、残りは空白で埋めます。デバイスグループ名を指定する場合、ボリューム番号も一緒に指定します。
ボリューム番号
C'06'
ファイルがカタログされていない場合は、ボリューム番号を左詰めで指定し、残りは空白で埋めます。ボリューム番号を指定する場合、デバイスグループ名も一緒に指定します。
リモート
仮想ファイル名
C'08'
仮想ファイル名を左詰めで指定し、残りは空白で埋めます。ただし、名前の最初の文字に区切り記号を指定するか、空白を含むことはできません。
仮想ファイル名の区切り文字
C'19'
仮想ファイルの区切り文字は先頭の1バイト目に指定します。区切り文字を省略した場合は「/」が指定されたものとみなします。2バイト目は任意の値です。ただし、区切り文字として空白を指定することはできません。
保存タイプ
C'09'
リモート・ファイルに転送データを保存する場合の保存タイプを指定します。
-
1:ファイルの先頭から保存(置換、省略値)
-
2:既存データの後に保存(拡張)
OpenFrameでは指定の有無に関係なく、ファイル先頭から保存します。
アクセスパスワード(FTAM)
C'10'
アクセスパスワードは以下の形式で指定します。
長さ(2バイト) + データ形式(2バイト) + パスワード(8バイト)
データ形式は以下のとおりです。
-
0:バイナリ
-
1:英数字
OpenFrameではサポートされていません。
共通
データ形式
C'11'
データ形式は以下のとおりです。
-
0:バイナリレコード(省略値)
-
1:テキスト
-
2:バイナリ
-
3:バイナリフォーマット
-
100:UNKNOWN
UNKNOWNを指定する場合、リモート・ノード指定のデータ形式に応じてファイルを転送します。
FTPプロトコルとの対応関係は以下のとおりです。
-
テキスト:ASCIIに対応します。
-
バイナリとバイナリレコード:バイナリに対応します。
-
バイナリフォーマット:バイナリフォーマットに対応します。(FTP+の場合に指定できます)
-
UNKNOWNおよびFTPプロトコルで、バイナリフォーマットを指定するとエラーが発生します。
OpenFrameではFTPのみをサポートしており、バイナリとテキストのみ使用できます。
ユニバーサル・クラス(FTAM)
C'18'
データ形式がテキストの場合、ユニバーサル・クラス番号(使用する文字セットを選択)を指定します。省略した場合は、25(図形文字セット)が指定されたものとみなします。 OpenFrameではサポートされていません。
データ圧縮 (FTAM、FTP+)
C'42'
データタイプがINTAP-1またはFTP+プロトコルの場合、送信データを圧縮するかどうかを指定します。
-
1:圧縮しない
-
2:圧縮する(FTAMまたはFTP+の場合、FLDC1方式)
-
3:圧縮する(FLDC2方式)
OpenFrameではサポートされていません。
転送速度の上限値
C'60'
転送速度の上限値を指定します。
-
1~1024KB/s
OpenFrameではサポートされていません。
ローカル
ユーザー名
C'71'
ユーザー名(7文字以内の英数字)を左詰めで指定し、残りは空白で埋めます。ユーザー名を指定する場合、パスワードも一緒に指定します。
ユーザー
C'72'
ユーザー・パスワードを左詰めで指定し、残りは空白で埋めます。ユーザー・パスワードを指定する場合、ユーザー名も一緒に指定します。
グループ名
C'79'
RACFグループ名を左詰めで指定し、残りは空白で埋めます。OpenFrameではサポートされていません。
リモート
リモート・ユーザー名
C'17'
リモート・ユーザー名を左詰めで指定し、残りは空白で埋めます。
リモート・ノードのセキュリティに合わせて、リモート・ユーザー名とリモート・パスワードのいずれかのみ指定することもできます。
また、FTPプロトコルを使用する場合、リモート・ノードとコネクションが確立されていないときは必ず指定が必要です。リモート・パスワード
リモート・ユーザーのパスワードを指定します。
識別子「C'81'」と「C'85'」は、リモート・パスワードを指定するための同じパラメータです。リモート・パスワードを英数字で指定する場合は、識別子「C'81'」形式で指定します。
リモート・パスワードを16進数と英数字で指定する場合は、識別子「C'85'」形式で指定します。識別子「C'81'」と「C'85'」のパラメータを同時に指定した場合は、後で指定したパラメータが採用されます。
C'81'
リモート・パスワードを英数字で通知する場合、左詰めで指定し、残りは空白で埋めます。
リモート・ノードのセキュリティに合わせて、リモート・ユーザー名とリモート・パスワードのいずれかのみ指定することもできます。C'85'
リモート・パスワードを英数字または16進数で通知する場合、左詰めで指定します。
リモート・ノードのセキュリティに合わせて、リモート・ユーザー名とリモート・パスワードのいずれかのみ指定することもできます。リモート・パスワードは以下の形式で指定できます。
長さ(2バイト) + データ形式(2バイト) + パスワード(8バイト)
データ形式は以下のとおりです。
-
0:バイナリ
-
1:英数字
OpenFrameではサポートされていません。
リモート・グループ名
C'80'
リモート・ノードに送信するRACFグループ名を左詰めで指定し、残りは空白で埋めます。
OpenFrameではサポートされていません。
コード変換
コード変換の形式
C'74'
コード変換の形式を指定します。
-
0:定義に従う(省略値)
-
1:コード変換なし
-
2:コード変換あり
コード変換ありを指定する場合は、コード変換テーブル名も一緒に指定します。
OpenFrameではサポートされていません。
コード変換
C'82'
コード変換テーブル名を以下の形式で指定します。
-
3:EBCDIC - ASCII
コード変換テーブル名を指定する場合、コード変換の形式は「2」を指定します。
OpenFrameではサポートされていません。
終了記号
C’FF'
終了記号にはパラメータ値がありません。
-
-
以下は、RCVILEの説明です。
区分 パラメータ コード 説明 共通
要求識別子
C'90'
ユーザーが任意の値を指定します。この値はファイル転送の完了通知に含まれ、ファイル転送要求などを確認するときに使用されます。
要求値
C'91'
要求値を指定します。
-
0:空白値(省略値)
-
1:完了戻り値
アプリケーション名
C'92'
RCVFILEサービスを要求したアプリケーション名を左詰めで指定し、残りは空白で埋めます。
アプリケーションの動作環境
C'26'
要求値が空白値の場合、ファイル転送の完了通知先のアプリケーションの動作環境を指定します。
-
1:TSS環境で動作するユーザープログラム
-
2:バッチ環境で動作するアプリケーション(省略値)
OpenFrameではサポートされていません
完了通知先のアプリケーション名
C'25'
要求値が空白値の場合、ファイル転送の完了通知先のアプリケーション名を左詰めで指定し、残りは空白で埋めます。このパラメータを省略した場合は、SNDFILEサービスを要求したユーザープログラムにファイル転送の完了を通知します。
OpenFrameでは省略した場合の動作が適用されます。リモート・ノード名
C'01'
リモート・ノード名を左詰めで指定し、残りは空白で埋めます。
関連付け
C'02'
ファイル転送サービスが完了したとき、関連付け(association)を維持するかどうかを指定します。
-
1:切断する
-
2:維持する(省略値)
OpenFrameでは指定の有無に関係なく、転送サービスが完了したときに関連付けを切断します。
ローカル
ファイル名
C'03'
ファイル名を左詰めで指定し、残りは空白で埋めます。
メンバー名
C'04'
区分編成ファイルの場合、メンバー名を左詰めで指定し、残りは空白で埋めます。
ファイルの割り当て
C'05'
他のジョブと共有できるようにファイルを割り当てるかどうかを指定します。
-
0:共有するために割り当てる(省略値)
-
1:排他的に割り当てる
保存タイプ
C'09'
受信したデータをファイルに保存する際の保存形式を指定します。
-
1:ファイルの先頭から保存(置換、省略値)
-
2:既存データの後に保存(拡張)
OpenFrameでは指定の有無に関係なく、ファイル先頭から保存します。
メンバーの置換
C'15'
受信する区分編成ファイルにメンバー名と同じ名前を持つメンバーが存在する場合、置換するかどうかを指定します。
-
0:定義に従う(省略値)
-
1:置換する
-
2:置換しない
ファイルの属性
C'14'
ファイルの属性以下の形式で指定します。レコードフォーマットは、左詰めで指定し、残りは空白で埋めます。
レコードフォーマット(4バイト)+レコード長(2バイト)+ブロック長(2バイト)
-
レコードフォーマット
-
{F[B][A] ] | [V[B][A]}
-
-
レコード長
-
形式:バイナリ
-
範囲:1から32760
-
-
ブロック長
-
形式:バイナリ
-
範囲:1から32760
-
デバイスグループ名
C'16'
ファイルがカタログされていない場合は、デバイスグループ名を左詰めで指定し、残りは空白で埋めます。デバイスグループ名を指定する場合、ボリューム番号も一緒に指定します。
ボリューム番号
C'06'
ファイルがカタログされていない場合は、ボリューム番号を左詰めで指定し、残りは空白で埋めます。ボリューム番号を指定する場合、デバイスグループ名も一緒に指定します。
リモート
仮想ファイル名
C'08'
仮想ファイル名を左詰めで指定し、残りは空白で埋めます。ただし、名前の最初の文字に区切り記号を指定するか、空白を含むことはできません。
仮想ファイル名の区切り文字
C'19'
仮想ファイルの区切り文字は先頭の1バイト目に指定します。区切り文字を省略した場合は「/」が指定されたものとみなします。2バイト目は任意の値です。ただし、区切り文字として空白を指定することはできません。
アクセスパスワード(FTAM)
C'10'
アクセスパスワードは以下の形式で指定します。
長さ(2バイト) + データ形式(2バイト) + パスワード(8バイト)
データ形式は以下のとおりです。
-
0:バイナリ
-
1:英数字
OpenFrameではサポートされていません。
共通
データ形式
C'11'
データ形式は以下のとおりです。
-
0:バイナリレコード(省略値)
-
1:テキスト
-
2:バイナリ
-
3:バイナリフォーマット
-
100:UNKNOWN
UNKNOWNを指定する場合、リモート・ノード指定のデータ形式に応じてファイルを転送します。
FTPプロトコルとの対応関係は以下のとおりです。
-
テキスト:ASCIIに対応します。
-
バイナリとバイナリレコード:バイナリに対応します。
-
バイナリフォーマット:バイナリフォーマットに対応します。(FTP+の場合に指定できます)
-
UNKNOWNおよびFTPプロトコルで、バイナリフォーマットを指定するとエラーが発生します。
OpenFrameではFTPのみをサポートしており、バイナリとテキストのみ使用できます。
ユニバーサル・クラス(FTAM)
C'18'
データ形式がテキストの場合、ユニバーサル・クラス番号(使用する文字セットを選択)を指定します。省略した場合は、25(図形文字セット)が指定されたものとみなします。 OpenFrameではサポートされていません。
データ圧縮(FTAM、FTP+)
C'42'
データタイプがINTAP-1またはFTP+プロトコルの場合、送信データを圧縮するかどうかを指定します。
-
1:圧縮しない
-
2:圧縮する(FTAMまたはFTP+の場合、FLDC1方式)
-
3:圧縮する(FLDC2方式)
OpenFrameではサポートされていません。
ローカル
ユーザー名
C'71'
ユーザー名(7文字以内の英数字)を左詰めで指定し、残りは空白で埋めます。ユーザー名を指定する場合、パスワードも一緒に指定します。
ユーザー
C'72'
ユーザー・パスワードを左詰めで指定し、残りは空白で埋めます。ユーザー・パスワードを指定する場合、ユーザー名も一緒に指定します。
グループ名
C'79'
RACFグループ名を左詰めで指定し、残りは空白で埋めます。OpenFrameではサポートされていません。
リモート
リモート・ユーザー名
C'17'
リモート・ユーザー名を左詰めで指定し、残りは空白で埋めます。 リモート・ノードのセキュリティに合わせて、リモート・ユーザー名とリモート・パスワードのいずれかのみ指定することもできます。
また、FTPプロトコルを使用する場合、リモート・ノードとコネクションが確立されていないときは必ず指定が必要です。リモート・パスワード
リモート・ユーザーのパスワードを指定します。 識別子「C'81'」と「C'85'」は、リモート・パスワードを指定するための同じパラメータです。リモート・パスワードを英数字で指定する場合は、識別子「C'81'」形式で指定します。
リモート・パスワードを16進数と英数字で指定する場合は、識別子「C'85'」形式で指定します。識別子「C'81'」と「C'85'」のパラメータを同時に指定した場合は、後で指定したパラメータが採用されます。
C'81'
リモート・パスワードを英数字で通知する場合、左詰めで指定し、残りは空白で埋めます。
リモート・ノードのセキュリティに合わせて、リモート・ユーザー名とリモート・パスワードのいずれかのみ指定することもできます。C'85'
リモート・パスワードを英数字または16進数で通知する場合、左詰めで指定します。
リモート・ノードのセキュリティに合わせて、リモート・ユーザー名とリモート・パスワードのいずれかのみ指定することもできます。リモート・パスワードは以下の形式で指定できます。
長さ(2バイト) + データ形式(2バイト) + パスワード(8バイト)
データ形式は以下のとおりです。
-
0:バイナリ
-
1:英数字
OpenFrameではサポートされていません。
リモート・グループ名
C'80'
リモート・ノードに送信するRACFグループ名を左詰めで指定し、残りは空白で埋めます。
OpenFrameではサポートされていません。
コード変換
コード変換の形式
C'74'
コード変換の形式を指定します。
-
0:定義に従う(省略値)
-
1:コード変換なし
-
2:コード変換あり
コード変換ありを指定する場合は、コード変換テーブル名も一緒に指定します。
OpenFrameではサポートされていません。
コード変換
C'82'
コード変換テーブル名を以下の形式で指定します。
-
3:EBCDIC - ASCII
コード変換テーブル名を指定する場合、コード変換の形式は「2」を指定します。
OpenFrameではサポートされていません。
終了記号
C’FF'
終了記号にはパラメータ値がありません。
-
-
-
エラーコード
以下は、エラータイプとエラーコードの説明です。OpenFrameでサポートされる項目についてのみ説明します。
エラータイプ エラーコード 詳細コード 説明 0
0
0
正常終了した場合です。
10
36
データタイプの値が正しくありません。
42
ユーザー名とユーザー・パスワードのいずれかのみを指定したか、リモート・ユーザー名とユーザー・パスワードのいずれかのみを指定した場合です。
105
要求タイプの値が正しくない場合です。
151
アプリケーションの動作環境の値が正しくありません。
155
インターフェース・レベルの値が正しくありません。
156
パラメータの識別子が正しくないか、終了記号(C’FF')が指定されていない場合です。
159
必須パラメータが省略された場合です。
40
340
リモート・ノードとの関連付け(association)に失敗した場合です。
80
499
分析できないエラーが発生した場合です。
-
呼び出し例
以下は、SNDFILEの呼び出し例です。
01 P-INTLVL PIC X(002) VALUE '11'. 01 P-REQCODE PIC X(002) VALUE '01'. 01 P-RC. 03 P-RC-CODE1 PIC 9(004) COMP. 03 P-RC-CODE2 PIC 9(004) COMP. 03 P-RC-CODE3 PIC 9(005) COMP. 01 P-SNDFILE. 03 SNDFILE-TYP-PARM. 05 SNDFILE-TYP-ID PIC X(002) VALUE '91'. 05 SNDFILE-TYP-CONT PIC 9(002) VALUE 1 COMP. 03 SNDFILE-APL-PARM. 05 SNDFILE-APL-ID PIC X(002) VALUE '92'. 05 SNDFILE-APL-CONT PIC X(008) VALUE 'SNDFILE '. 03 SNDFILE-SYS-PARM. 05 SNDFILE-SYS-ID PIC X(002) VALUE '01'. 05 SNDFILE-SYS-CONT PIC X(008). 03 SNDFILE-FILE-PARM. 05 SNDFILE-FILE-ID PIC X(002) VALUE '03'. 05 SNDFILE-FILE-CONT PIC X(044). 03 SNDFILE-STYP-PARM. 05 SNDFILE-STYP-ID PIC X(002) VALUE '16'. 05 SNDFILE-STYP-CONT PIC X(008) VALUE 'DA '. 03 SNDFILE-VOL-PARM. 05 SNDFILE-VOL-ID PIC X(002) VALUE '06'. 05 SNDFILE-VOL-CONT PIC X(006). 03 SNDFILE-VFILE-PARM. 05 SNDFILE-VFILE-ID PIC X(002) VALUE '08'. 05 SNDFILE-VFILE-CONT PIC X(064). 03 SNDFILE-DTYPE-PARM. 05 SNDFILE-DTYPE-ID PIC X(002) VALUE '11'. 05 SNDFILE-DTYPE-CONT PIC 9(002) COMP. 03 SNDFILE-USER-PARM. 05 SNDFILE-USER-ID PIC X(002) VALUE '17'. 05 SNDFILE-USER-CONT PIC X(008). 03 SNDFILE-PSWD-PARM. 05 SNDFILE-PSWD-ID PIC X(002) VALUE '81'. 05 SNDFILE-PSWD-CONT PIC X(008). 03 SNDFILE-END PIC X(002) VALUE 'FF'. 03 P-REQNUM PIC 9(005) COMP. 03 P-TRANCOMP. 05 P-DATA1 PIC X(154). 05 P-DATA2 PIC X(020). 05 P-DATA3 PIC X(050). 05 P-DATA4 PIC X(080). 05 P-DATA5 PIC X(108). ... PROCEDURE DIVISION. CALL 'KZAAPI' USING P-INTLVL P-REQCODE P-RC P-SNDFILE P-REQNUM P-TRANCOMP.
以下は、RCVFILEの呼び出し例です。
01 P-INTLVL PIC X(002) VALUE '11'. 01 P-REQCODE PIC X(002) VALUE '02'. 01 P-RC. 03 P-RC-CODE1 PIC 9(004) COMP. 03 P-RC-CODE2 PIC 9(004) COMP. 03 P-RC-CODE3 PIC 9(005) COMP. 01 P-RCVFILE. 03 RCVFILE-TYP-PARM. 05 RCVFILE-TYP-ID PIC X(002) VALUE '91'. 05 RCVFILE-TYP-CONT PIC 9(002) VALUE 1 COMP. 03 RCVFILE-APL-PARM. 05 RCVFILE-APL-ID PIC X(002) VALUE '92'. 05 RCVFILE-APL-CONT PIC X(008) VALUE 'RCVFILE '. 03 RCVFILE-SYS-PARM. 05 RCVFILE-SYS-ID PIC X(002) VALUE '01'. 05 RCVFILE-SYS-CONT PIC X(008). 03 RCVFILE-FILE-PARM. 05 RCVFILE-FILE-ID PIC X(002) VALUE '03'. 05 RCVFILE-FILE-CONT PIC X(044). 03 RCVFILE-VFILE-PARM. 05 RCVFILE-VFILE-ID PIC X(002) VALUE '08'. 05 RCVFILE-VFILE-CONT PIC X(064). 03 RCVFILE-DTYPE-PARM. 05 RCVFILE-DTYPE-ID PIC X(002) VALUE '11'. 05 RCVFILE-DTYPE-CONT PIC 9(002) COMP. 03 RCVFILE-USER-PARM. 05 RCVFILE-USER-ID PIC X(002) VALUE '17'. 05 RCVFILE-USER-CONT PIC X(008). 03 RCVFILE-PSWD-PARM. 05 RCVFILE-PSWD-ID PIC X(002) VALUE '81'. 05 RCVFILE-PSWD-CONT PIC X(008). 03 RCVFILE-END PIC X(002) VALUE 'FF'. 03 P-REQNUM PIC 9(005) COMP. 03 P-TRANCOMP. 05 P-DATA1 PIC X(154). 05 P-DATA2 PIC X(020). 05 P-DATA3 PIC X(050). 05 P-DATA4 PIC X(080). 05 P-DATA5 PIC X(108). ... PROCEDURE DIVISION. CALL 'KZAAPI' USING P-INTLVL P-REQCODE P-RC P-SNDFILE P-REQNUM P-TRANCOMP.