# 履歴検索API

HULFTの集配信履歴ファイルから検索条件にあった情報を検索します。

言語環境（LE）で動作するため、LEライブラリー（OS導入時、省略時のライブラリー名：CEE.SCEERUN）が必要です。

## 呼び出し形式（COBOL）

    CALL 'XRLOGAP' USING パラメーターエリア 履歴レコードエリア

パラメーターエリア説明

項目 | 属性 | 長さ | 説明
--- | --- | --- | ---
動作バージョン | キャラクター | 6 | 検索したい履歴フォーマットのバージョンおよびパラメーターエリアのバージョンを指定します。 以下のいずれかを指定してください。 V08L01 V08L02 V08L04 APIは、指定されたバージョンのフォーマットにあわせて履歴ファイルの項目を取得します。取得したい項目にあわせてバージョンを指定してください。
コマンド | キャラクター | 3 | 以下のコマンドを実行します。
GTP | 該当履歴情報を検索
SQP | 該当情報に位置付ける
GTA | 該当履歴情報を検索
GTN | 該当履歴情報の次の情報を検索
SQN | 位置付けた情報を読む
OPN | 集配信履歴ファイルをオープン
CLS | 集配信履歴ファイルをクローズ
実行オプション | キャラクター | 1 | I | コマンドに“OPN”を指定した場合に設定
F | ファイルIDで検索する場合に設定
S | ホスト名で検索する場合に設定
位置付けオプション | キャラクター | 1 | 位置付けた情報以降を検索したい場合、“H”を指定します。
リザーブ | キャラクター | 2 | “LOW-VALUE（0x00）”を指定してください。
検索する管理情報 | キャラクター | 1 | S | 配信履歴情報を検索する場合に指定します。
R | 集信履歴情報を検索する場合に指定します。
J | ジョブ実行履歴情報を検索する場合に指定します。
C | 要求受付履歴情報を検索する場合に指定します。
検索キー | キャラクター | 50 | 検索したいファイルID、またはホスト名を指定します。
検索開始日付 | バイナリー | 4 | 検索時、該当日付の履歴を取得したい場合に指定します。
検索開始時間 | バイナリー | 4 | 検索時、該当時間の履歴を取得したい場合に指定します。 検索開始時間を指定する場合は、検索開始日付の指定が必須です。
完了コード | バイナリー | 2 | 実行後の完了コードが設定されます。
VSAM FDBK | バイナリー | 2 | 実行後、VSAMアクセスで異常が発生した場合に設定されます。
リザーブ | キャラクター | 20 | “LOW-VALUE（0x00）”を指定してください。

【各項目の組み合わせ】

コマンド | 実行 オプション | 位置付 オプション | 検索キー | 検索 開始日付 | 検索 開始時間 | 概要
--- | --- | --- | --- | --- | --- | ---
OPN | I | スペース | スペース | ゼロ | ゼロ | 集配信履歴ファイルをオープンする。
CLS | スペース | スペース | スペース | ゼロ | ゼロ | 集配信履歴ファイルをクローズする。
GTP | スペース | スペース | スペース | ゼロ | ゼロ | 存在する履歴の中でファイルID、日付、時間がEBCDIC順で一番小さいレコードを1件読み込む。
SQP | スペース | スペース | スペース | 日付 | 時間 | 指定された日付時間以降で、最も古いレコードを1件読み込む。
SQP | スペース 以外 | スペース | スペース | ゼロ | ゼロ | 存在する履歴の中で日付時間の最も新しいレコードを1件読み込む。 = 備考 = ジョブ実行履歴に対して行うことはできません。
GTA | F | スペース | ファイルID | ゼロ | ゼロ | 指定されたファイルIDの最も古いレコードを1件読み込む。
GTA | F | H | ファイルID | 日付 | ゼロ | 指定されたファイルIDで、指定された日付の最も古いレコードを1件読み込む。
GTA | S | スペース | ホスト名 | ゼロ | ゼロ | 指定されたホスト名の最も古いレコードを1件読み込む。
GTA | S | H | ホスト名 | 日付 | ゼロ | 指定されたホスト名で、指定された日付の最も古いレコードを1件読み込む。
GTN | スペース | スペース | 変更不可 | ゼロ | ゼロ | 前回読み込んだ次に古いレコードを1件読み込む。
GTN | F | スペース | 変更不可 | ゼロ | ゼロ | 前回読み込んだレコードと同一ファイルIDで次に古いレコードを1件読み込む。（同一ファイルIDがなくなったらエラーを返す）
GTN | S | スペース | 変更不可 | ゼロ | ゼロ | 前回読み込んだレコードと同一ホスト名で次に古いレコードを1件読み込む。（同一ホスト名がなくなったらエラーを返す）
SQN | スペース | スペース | 変更不可 | ゼロ | ゼロ | 前回読み込んだレコードの次に存在するレコードを読み込む。
SQN | スペース 以外 | スペース | 変更不可 | ゼロ | ゼロ | 前回読み込んだレコードの直前に存在するレコードを読み込む。

注意

「検索開始日付」に「日付」と記載されている場合は、ゼロはセットしないでください。誤動作の原因となります。

履歴レコードエリア

履歴レコードエリアのフォーマットは、動作バージョンで指定したバージョンによって異なります。

履歴レコードエリアの詳細は、「履歴ファイルのフォーマット」を参照してください。

注意

APIを使用して履歴を取得した場合は、各履歴ファイルのレコードの先頭にあるキーフィールド項目は取得されません。以降の項目が詰められたフォーマットとなります。

## 完了コード

完了コード | 内容
--- | ---
0 | 正常に実行しました。
1 | コマンドの設定内容に誤りがあります。
2 | オプション情報の設定内容に誤りがあります。
3 | 集配信履歴ファイルのオープンに失敗しました。
4 | 集配信履歴ファイルのクローズに失敗しました。
7 | 検索処理で異常が発生しました。詳細情報が、VSAM FDBKに設定されます。
8 | 次情報の検索処理で異常が発生しました。詳細情報が、VSAM FDBKに設定されます。
10 | 該当情報は存在しません。
11 | 次の情報は存在しません。
14 | 動作バージョンがサポートされていません。
15 | 検索キーの設定内容に誤りがあります。
16 | 本コマンドで指定できる管理情報ではありません。

注意

実行するJCLに以下のDDステートメントの記述をしてください。

- JCL例

    //XRLOG    DD DSN=HULFT.LOG,DISP=SHR
    //XRLOG1   DD DSN=HULFT.LOG.PATH1,DISP=SHR
    //XRLOG2   DD DSN=HULFT.LOG.PATH2,DISP=SHR
    //XRSYSIN  DD DSN=HULFT.PARMLIB(HULPRM),DISP=SHR

DD名 | 項目名 | 説明
--- | --- | ---
XRLOG | HULFT.LOG | 集配信履歴ファイルIDキーファイル
XRLOG1 | HULFT.LOG.PATH1 | 集配信履歴ホスト名キーファイル
XRLOG2 | HULFT.LOG.PATH2 | 集配信履歴日付キーファイル
XRSYSIN | HULFT.PARMLIB(HULPRM) | システム動作環境設定ファイル

## 使用例

COBOLで使用する場合

履歴検索API（ XRLOGAP）を利用して、集信履歴を検索するサンプルプログラムです。

サンプルプログラムは、HULFT JCLライブラリー内のメンバー名「SMPLOGAP」です。

検索するデータ

集信履歴の一番古いデータ

          *
          * GET HULFT RECEIVE LOG RECORD SAMPLE
          *
           IDENTIFICATION     DIVISION.
           PROGRAM-ID.        SMPLOGAP.
           ENVIRONMENT        DIVISION.
           DATA               DIVISION.
           WORKING-STORAGE    SECTION.
          *
          * XRLOGAP PARAMETER AREA
          *
           01  XRLOGAP-PARM.
               02 XRLOGAP-VER      PIC X(6).
               02 XRLOGAP-COMMAND  PIC X(3).
               02 XRLOGAP-EXECOPT  PIC X(1).
               02 XRLOGAP-POINTOPT PIC X(1).
               02 XRLOGAP-RESERVE1 PIC X(2).
               02 XRLOGAP-INFO     PIC X(1).
               02 XRLOGAP-KEY      PIC X(50).
               02 XRLOGAP-DATE     PIC 9(8)  COMP.
               02 XRLOGAP-TIME     PIC 9(8)  COMP.
               02 XRLOGAP-ERRCD    PIC 9(4)  COMP.
               02 XRLOGAP-FDBK     PIC 9(4)  COMP.
               02 XRLOGAP-RESERVE2 PIC X(20).
          *
          * XRLOGAP 1 LOG RECORD AREA
          *
           01  XRLOGAP-RECORD  PIC X(1600).
          *------------------------------------------------*
           PROCEDURE          DIVISION.
          *
          * XRLOGAP PARAMETER AREA INITIALIZATION
          *
               INITIALIZE XRLOGAP-PARM.
               INITIALIZE XRLOGAP-RECORD.
          *
          * HULFT.LOG OPEN
          *
               MOVE 'V10L02'       TO XRLOGAP-VER.
               MOVE 'OPN'          TO XRLOGAP-COMMAND.
               MOVE 'I'            TO XRLOGAP-EXECOPT.
               MOVE LOW-VALUE      TO XRLOGAP-RESERVE1.
               MOVE 'R'            TO XRLOGAP-INFO.
               MOVE ZERO           TO XRLOGAP-DATE.
               MOVE ZERO           TO XRLOGAP-TIME.
               MOVE LOW-VALUE      TO XRLOGAP-RESERVE2.
               CALL 'XRLOGAP' USING XRLOGAP-PARM XRLOGAP-RECORD.
          *
          * GET THE OLDEST RECORD FROM HULFT RECEIVE LOG FILE
          *
               MOVE 'V10L02'       TO XRLOGAP-VER.
               MOVE 'GTA'          TO XRLOGAP-COMMAND.
               MOVE 'F'            TO XRLOGAP-EXECOPT.
               MOVE SPACE          TO XRLOGAP-POINTOPT.
               MOVE 'R'            TO XRLOGAP-INFO.
               MOVE 'FILEID'       TO XRLOGAP-KEY.
               CALL 'XRLOGAP' USING XRLOGAP-PARM XRLOGAP-RECORD.
               DISPLAY XRLOGAP-RECORD.
          *
          * HULFT.LOG CLOSE
          *
               MOVE 'V10L02'       TO XRLOGAP-VER.
               MOVE 'CLS'          TO XRLOGAP-COMMAND.
               MOVE SPACE          TO XRLOGAP-EXECOPT.
               MOVE SPACE          TO XRLOGAP-POINTOPT.
               MOVE 'R'            TO XRLOGAP-INFO.
               MOVE SPACE          TO XRLOGAP-KEY.
               MOVE ZERO           TO XRLOGAP-DATE.
               MOVE ZERO           TO XRLOGAP-TIME.
               CALL 'XRLOGAP' USING XRLOGAP-PARM XRLOGAP-RECORD.
          *
               STOP RUN.