カタログ管理API

本付録では、カタログ管理APIを使用してカタログ・エントリとデータセットを管理する方法について説明します。

1. 概要

OpenFrameが提供するカタログ管理APIを使用して、カタログ・エントリの削除・検索など、カタログとデータセットを管理することができます。

カタログ管理APIを使用してプログラムを作成するには、OpenFrameバイナリと一緒に配布されるamsu.hヘッダー・ファイルをユーザー・プログラムに含める必要があり、かつ、ユーザー・プログラムをコンパイルする際、libams.soライブラリをリンクする必要があります。

カタログ管理APIは、以下のように分類できます。

  • 初期化と終了処理

    API 説明

    amsu_initialize()

    カタログ管理のための初期化を行います。

    amsu_finalize()

    カタログ管理を終了する処理を行います。

  • ボリューム情報

    API 説明

    amsu_volume_list()

    システムに登録されているボリューム・リストを取得します。

    amsu_default_volume()

    システムに登録されているデフォルト・ボリュームを取得します。

    amsu_volume_path()

    特定のボリュームのディレクトリ・パスを取得します。

  • カタログ検索

    API 説明

    amsu_use_catalogs()

    任意のカタログ検索順を指定します。

    amsu_search_entries()

    カタログから特定の項目を検索します。

    amsu_master_catalog()

    システムに登録されているマスター・カタログ情報を取得します。

    amsu_candidate_catalog()

    特定のデータセットをカタログ化するための対象カタログを検索します。

  • ファイル・パス解決

    API 説明

    amsu_filepath2()

    特定のデータセットのUNIXファイル・パスを取得します。

    amsu_filename2()

    特定のデータセットのファイル名を取得します。

  • エントリ管理

    API 説明

    amsu_delete()

    カタログに登録されているデータセットを削除します。

    amsu_info()

    カタログに登録されている項目情報を読み取ります。

    amsu_assoc()

    カタログに登録されている項目と関連した一覧を取得します。

2. 初期化と終了処理

2.1. amsu_initialize()

カタログ管理のための初期化を行います。カタログの管理に必要なリソースをメモリにロードします。この関数を呼び出さずに他のカタログ管理APIを使用するとエラーが発生するので、必ず初期化してください。

  • プロトタイプ

    int amsu_initialize();

  • 戻り値

    正常に実行された場合は0を返し、エラーが生じた場合は負数のエラーコードを返します。

2.2. amsu_finalize()

カタログ管理を終了する場合に呼び出します。カタログ管理のためにメモリにロードしたリソースを削除します。

  • プロトタイプ

    int amsu_finalize();

  • 戻り値

    正常に実行された場合は0を返し、エラーが生じた場合は負数のエラーコードを返します。

3. ボリューム情報

3.1. amsu_volume_list()

システムに登録されているボリューム・リストを取得します。

  • プロトタイプ

    int amsu_volume_list(int *count, char *volser[]);

  • パラメータ

    パラメータ 説明

    count(出力)

    volserに与えられたバッファー・サイズ(入力)と登録されたボリューム数です。

    volser(出力)

    登録されたボリューム・シリアルを保存するためのバッファーです。

  • 戻り値

    正常に実行された場合は0を返し、エラーが生じた場合は負数のエラーコードを返します。

3.2. amsu_default_volume()

システムに登録されているデフォルト・ボリュームを取得します。

  • プロトタイプ

    int amsu_default_volume(char *volser);

  • パラメータ

    パラメータ 説明

    volser(出力)

    デフォルト・ボリューム・シリアルを保存するためのバッファーです。

  • 戻り値

    正常に実行された場合は0を返し、エラーが生じた場合は負数のエラーコードを返します。

3.3. amsu_volume_path()

特定のボリュームのディレクトリ・パスを取得します。

  • プロトタイプ

    int amsu_volume_path(char *volser, char *vpath);

  • パラメータ

    パラメータ 説明

    volser(入力)

    ディレクトリ・パスを確認するボリューム・シリアルです。

    vpath(出力)

    ディレクトリ・パスを保存するためのバッファーです。

  • 戻り値

    正常に実行された場合は0を返し、エラーが生じた場合は負数のエラーコードを返します。

4. カタログ検索

4.1. amsu_use_catalogs()

任意のカタログ検索順を指定します。

  • プロトタイプ

    int amsu_use_catalogs(char **cat_names);
int amsu_use_catalog(char *cat_name);

  • パラメータ

    パラメータ 説明

    cat_names(入力)

    カタログの検索時に優先して検索するカタログ名のリストです。

    cat_name(入力)

    カタログの検索時に優先して検索するカタログ名です。

  • 戻り値

    正常に実行された場合は0を返し、エラーが生じた場合は負数のエラーコードを返します。

4.2. amsu_search_entries()

カタログで特定の項目を検索します。カタログの検索順は以下のとおりです。

  1. amsu_use_catalogs()によって指定されたカタログ

  2. filter_keyによって指定されたエイリアス・カタログ

  3. 前項で見つからなかった場合はマスター・カタログ

    • プロトタイプ

      int amsu_search_entries(char *filter_key, char *entry_types, int *count,
                        amsu_result_t *result, int flags);

    • パラメータ

      パラメータ 説明

      filter_key

      検索するカタログ・エントリの式です。

      （IN - 「*」「%」などのワイルドカード文字を含む）

      entry_types(入力)

      検索するカタログ・エントリのタイプです。（NULLの場合はすべて検索）

      count(出力)

      結果バッファーのサイズ(入力)と検索された項目の数です。

      result(出力)

      検索された項目を保存するバッファーです。

      flags(入力)

      カタログの検索オプションです。

    • 戻り値

      正常に実行された場合は0を返し、エラーが生じた場合は負数のエラーコードを返します。

    • 参考

      カタログ・エントリのタイプとカタログの検索オプションは、ams_user.hヘッダー・ファイルに定義されているマクロを参照します。

      マクロ 項目タイプ 説明

      AMSU_ENTRY_TYPE_NONVSAM

      'A'

      非VSAMです。

      AMSU_ENTRY_TYPE_GDG

      'B'

      世代データ・グループです。

      AMSU_ENTRY_TYPE_CLUSTER

      'C'

      VSAMクラスターです。

      AMSU_ENTRY_TYPE_DATA

      'D'

      データ・コンポーネントです。

      AMSU_ENTRY_TYPE_AIX

      'G'

      代替索引です。

      AMSU_ENTRY_TYPE_GDS

      'H'

      世代データセットです。

      AMSU_ENTRY_TYPE_INDEX

      'I'

      索引コンポーネントです。

      AMSU_ENTRY_TYPE_PATH

      'R'

      アクセス・パスです。

      AMSU_ENTRY_TYPE_UCAT

      'U'

      ユーザー・カタログです。

      AMSU_ENTRY_TYPE_ALIAS

      'X'

      エイリアスです。

      以下は、カタログ検索オプションのマクロです。

      マクロ 検索オプション 説明

      AMSU_SEARCH_DEFAULT

      0x00

      基本検索オプションです。

      AMSU_SEARCH_CLS_COMPS

      0x01

      クラスター名がフィルター・キーと一致する場合、コンポーネントが返されます。

      AMSU_SEARCH_1_CATALOG

      0x02

      1つだけのカタログが検索されます。

      カタログの検索結果は、以下のような構造体に格納されます。

      /* -------------------------- catalog search result -------------------- */
typedef struct _amsu_result_t {
    char        catname[AMSU_ENTRY_NAME_LENGTH+1];
    char        entname[AMSU_ENTRY_NAME_LENGTH+1];
    char        enttype;
} amsu_result_t;

4.3. amsu_master_catalog()

システムに登録されているマスター・カタログの情報を取得します。

  • プロトタイプ

    int amsu_master_catalog(char *mascat_name, char *mascat_vser);

  • パラメータ

    パラメータ 説明

    mascat_name(出力)

    マスター・カタログのデータセット名を保存するバッファーです。

    mascat_vser(出力)

    マスター・カタログのボリューム・シリアル番号を保存するバッファーです。

  • 戻り値

    正常に実行された場合は0を返し、エラーが生じた場合は負数のエラーコードを返します。

4.4. amsu_candidate_catalog()

特定のデータセットの対象カタログを検索します。

対象カタログは、以下の規則により決まります。

  1. データセット名がGDSの場合はGDGカタログ

  2. amsu_use_catalogs()によって指定されたカタログ

  3. データセット名によって指定されたエイリアス・カタログ

  4. 前項で決まらなかった場合はマスター・カタログ

    • プロトタイプ

      int amsu_candidate_catalog(char *dsname, char *cat_name);

    • パラメータ

      パラメータ 説明

      dsname(入力)

      カタログ化するデータセット名です。

      cat_name(出力)

      対象カタログの名前を保存するバッファーです。

    • 戻り値

      正常に実行された場合は0を返し、エラーが生じた場合は負数のエラーコードを返します。

5. ファイル・パス解決

5.1. amsu_filepath2()

特定のデータセットのファイル・パスを取得します。

  • プロトタイプ

    int amsu_filepath(char *dsname, char *volser, char *filepath);
int amsu_filepath2(char *dsname, char *membname, char *volser, char *filepath);

  • パラメータ

    パラメータ 説明

    dsname(入力)

    ファイル・パスを検索するデータセット名です。

    membname(入力)

    ファイル・パスを検索するPDSのメンバーです。

    volser(入力)

    指定されたデータセットが格納されているボリューム・シリアルです。

    filepath(出力)

    UNIXファイル・パスを保存するバッファーです。

  • 戻り値

    正常に実行された場合は0を返し、エラーが生じた場合は負数のエラーコードを返します。

5.2. amsu_filename2()

特定のデータセットのファイル名を取得します。

  • プロトタイプ

    int amsu_filename(char *dsname, char *filename);
int amsu_filename2(char *dsname, char *membname, char *filename);

  • パラメータ

    パラメータ 説明

    dsname(入力)

    ファイル名を検索するデータセット名です。

    membname(入力)

    ファイル名を検索するPDSのメンバーです。

    filename(出力)

    UNIXファイル名を保存するバッファーです。

  • 戻り値

    正常に実行された場合は0を返し、エラーが生じた場合は負数のエラーコードを返します。

6. エントリ管理

6.1. amsu_delete()

カタログに登録されている項目を削除します。

  • プロトタイプ

    int amsu_delete(char *cat_name, char *entry_name, char entry_type, int flags);

  • パラメータ

    パラメータ 説明

    cat_name(入力)

    削除する項目が登録されたカタログ名です。

    entry_name(入力)

    削除する項目がカタログされた名前です。

    entry_type(入力)

    削除する項目がカタログされたタイプです。

    flags(入力)

    カタログの削除オプションです。

  • 戻り値

    正常に実行された場合は0を返し、エラーが生じた場合は負数のエラーコードを返します。

6.2. amsu_info()

カタログに登録されている項目の情報を読み取ります。

  • プロトタイプ

    int amsu_info(char *cat_name, char *entry_name, char entry_type, void
              *entry_info, int flags);

  • パラメータ

    パラメータ 説明

    cat_name(入力)

    読み取る項目が登録されたカタログ名です。

    entry_name(入力)

    読み取る項目がカタログされた名前です。

    entry_type(入力)

    読み取る項目がカタログされたタイプです。

    flags(入力)

    カタログの削除オプションです。

  • 戻り値

    正常に実行された場合は0を返し、エラーが生じた場合は負数のエラーコードを返します。

  • 参考

    カタログ・エントリの情報は、項目タイプによってそれぞれ異なる構造体に格納されます。以下は、GDG項目の情報構造体を示しています。

    /* -------------------------- GDG info type ---------------------------- */

typedef struct _amsu_gdg_info_t {
    char        dscrdt2[8];     /* creation date */
    char        dsexdt2[8];     /* expiration date */
    char        ownerid[8];     /* owner of the data set */
    int16_t     gdglimit;       /* maximum number of GDS allowed */
    uint8_t     gdgattr;        /* GDG attributes - bit flags */
} amsu_gdg_info_t;

    GDG以外の項目については、ams_user.hヘッダー・ファイルに定義されている構造体を参照してください。

6.3. amsu_assoc()

カタログに登録されている項目と関連した項目の一覧を取得します。 )))

  • プロトタイプ

    int amsu_assoc(char *cat_name, char *entry_name, char entry_type, int
               *count, amsu_symbol_t *assocs);

  • パラメータ

    パラメータ 説明

    cat_name(入力)

    項目が登録されたカタログ名です。

    entry_name(入力)

    項目がカタログされた名前です。

    entry_type(入力)

    項目がカタログされたタイプです。

    count(出力)

    関連項目のバッファー長(入力)、関連項目の数です。

    assoc(出力)

    関連項目のバッファーです。

  • 戻り値

    正常に実行された場合は0を返し、エラーが生じた場合は負数のエラーコードを返します。

  • 参考

    関連項目の一覧は、以下の構造体に格納されます。

    /* -------------------------- catalog entry symbol --------------------- */

typedef struct _amsu_symbol_t {
    char        entname[AMSU_ENTRY_NAME_LENGTH+1];
    char        enttype;
} amsu_symbol_t;